Skip to main content

Getting Started with SCIM

This guide walks through a production-style SCIM rollout for AxonFlow Enterprise.

The goal is not just to get a green "test connection" result in your identity provider. The goal is to leave you with a provisioning setup that your IAM team can operate safely.

Before You Start​

You should have:

  • access to the AxonFlow customer portal for the target tenant
  • a user with the sso:configure permission
  • admin access to your identity provider
  • the real enterprise hostname for the target environment
  • a decision about whether you want to start with users only or users plus groups

If your organization is also rolling out SSO, do not assume SCIM and SSO have to go live at the same time. It is often cleaner to validate them in phases.

Step 1: Confirm the Right Base URL​

Your IdP needs the SCIM base URL for the enterprise portal domain that serves your tenant.

Use this format:

https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2

Examples of the endpoints derived from that base:

  • https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/Users
  • https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/Groups
  • https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/ServiceProviderConfig

Do not copy a fixed hostname from another environment or older documentation.

Step 2: Create a SCIM Token​

SCIM tokens are created from the authenticated portal side, not from the SCIM endpoint itself.

Portal endpoints:

  • GET /api/v1/scim/tokens
  • POST /api/v1/scim/tokens
  • DELETE /api/v1/scim/tokens/{tokenID}

Typical workflow:

  1. sign in to the customer portal
  2. navigate to the SCIM provisioning area
  3. create a token with a descriptive name such as okta-prod, entra-pilot, or onelogin-staging
  4. choose an expiration policy that fits the environment
  5. store the token value immediately

The plaintext token is only available at creation time. The portal stores the hash and a short prefix for later management.

Step 3: Configure the Identity Provider​

At a minimum, every SCIM 2.0 provider needs:

  • the base URL: https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2
  • bearer-token authentication
  • the token value created in the portal

Provider-specific details vary, so use the dedicated setup guides when available:

Step 4: Test Discovery and Authentication​

Validate the path before assigning real users.

Discovery should work without authentication​

curl -sS https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/ServiceProviderConfig \
  -H 'Accept: application/scim+json'

User listing should require a valid SCIM token​

curl -sS https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/Users \
  -H 'Authorization: Bearer scim_your_token_here' \
  -H 'Accept: application/scim+json'

If discovery works but authenticated user listing fails, the issue is usually one of:

  • wrong hostname
  • revoked or expired token
  • missing Bearer prefix in the IdP configuration
  • IdP or network path using the wrong environment

Step 5: Start with a Small Assignment Set​

For the first sync, do not assign an entire organization or large production group.

Start with:

  • one or two test users
  • a pilot group only if you explicitly want to validate group sync

This makes it much easier to understand create, update, and deactivate behavior before the rollout has broad impact.

Step 6: Verify the First Sync​

After assigning users in the IdP:

  1. run the IdP's connection test or on-demand provisioning flow
  2. confirm the request reaches AxonFlow
  3. verify that users appear in the target tenant
  4. inspect whether names, usernames, and email attributes landed as expected

What you want to verify first:

  • the correct tenant is receiving the users
  • userName and email values are usable
  • the account is active when it should be active
  • updates from the IdP are reflected correctly

Step 7: Validate Update and Deactivation​

A real enterprise rollout is not complete after "user create works."

Also validate:

  • profile updates
  • deactivation or disable flows
  • reactivation if your IdP supports it

This matters because many organizations discover lifecycle issues only after the first employee move or exit event.

Step 8: Enable Group Sync If Needed​

If your access model relies on groups:

  1. enable group provisioning in the IdP
  2. assign or push one pilot group
  3. verify the group arrives in AxonFlow
  4. only then start aligning synced groups to AxonFlow roles

If your initial rollout only needs user lifecycle automation, it is reasonable to defer group sync until after user provisioning is stable.

Step 9: Rotate to a Production Token​

Once the pilot works:

  1. create a production token from the portal
  2. update the IdP configuration
  3. validate provisioning again
  4. revoke the pilot token

This gives you a clean credential history and avoids leaving test tokens active longer than necessary.

  • the SCIM base URL points to the right enterprise environment
  • discovery endpoints respond without auth
  • /scim/v2/Users responds with the SCIM token
  • at least one test user provisions successfully
  • user updates work
  • deactivation works
  • groups sync if your rollout uses them
  • token rotation has been rehearsed

When to Pause the Rollout​

Stop and fix the setup before broad rollout if any of these are true:

  • users are landing in the wrong tenant
  • duplicate users are being created
  • deactivation is not behaving predictably
  • group sync is changing access in unexpected ways
  • tenant admins cannot tell which token or environment the IdP is using
Last updated on