Skip to main content

SCIM Troubleshooting Guide

This guide focuses on the problems that actually slow down enterprise SCIM rollouts:

  • wrong environment or wrong base URL
  • valid discovery but broken authenticated requests
  • user provisioning working while group sync fails
  • token lifecycle problems
  • IdP configuration that looks correct but targets the wrong tenant

First Checks​

Start with the smallest possible set of validations.

1. Discovery should work without authentication​

curl -sS -o /dev/null -w "%{http_code}\n" \
  https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/ServiceProviderConfig

Expected result: 200

2. Authenticated user listing should work with a valid token​

curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer scim_your_token_here" \
  -H "Accept: application/scim+json" \
  https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/Users

Expected result: 200

3. Confirm token metadata in the portal​

From the authenticated portal side:

  • list the tenant's SCIM tokens
  • confirm the expected token exists
  • check whether it has expired
  • check whether it has been revoked
  • inspect last_used_at to see whether the IdP is really hitting the token you think it is

Common Failure Patterns​

401 Unauthorized​

What it usually means​

  • the SCIM token is missing
  • the token is invalid, revoked, or expired
  • the IdP is not sending the header format the middleware expects

Current auth behavior that matters​

The SCIM middleware expects:

Authorization: Bearer scim_xxxxxxxxx

If the header is malformed or the token cannot be validated, the request fails with 401.

What to check​

  • confirm the token value in the IdP is current
  • verify whether the IdP wants the raw token or the full Bearer ... string
  • confirm the token has not been rotated or revoked
  • confirm the IdP is pointing at the right environment

400 Bad Request​

What it usually means​

  • invalid JSON
  • missing required user attributes
  • unsupported or malformed SCIM filter syntax
  • the request body does not match what the provider is expected to send

What to check​

  • userName is present
  • a valid email attribute is present where your IdP mapping expects it
  • custom attribute mapping is not producing malformed payloads
  • patch operations are valid SCIM operations, not an IdP-specific custom shape

404 Not Found​

What it usually means​

  • the IdP is trying to update or delete a user or group that no longer exists
  • the IdP has stale stored IDs
  • the environment URL is wrong

What to check​

  • verify the user or group still exists in the tenant
  • verify the IdP is targeting the correct enterprise environment
  • if needed, deassign and reassign the pilot user to recreate state cleanly

409 Conflict​

What it usually means​

  • duplicate usernames
  • duplicate identity records
  • the same user already exists under a different provisioning path

What to check​

  • whether the user was created manually or previously provisioned
  • whether multiple IdP applications are trying to control the same account
  • whether userName and email strategy are stable across the organization

Discovery Works but User Sync Fails​

This is one of the most common rollout patterns.

If ServiceProviderConfig works but /Users does not:

  • the network path is probably fine
  • the problem is usually token or IdP header configuration

That is why discovery and authenticated user listing should always be tested separately.

Users Sync but Groups Do Not​

Typical causes:

  • group provisioning was never enabled in the IdP
  • the app assignment includes users but not the groups you expect
  • the IdP supports group sync differently from user sync
  • the rollout moved to group-based access before the basic provisioning path was stable

The right response is usually not "keep retrying." It is:

  1. narrow to one pilot group
  2. confirm that group is in scope
  3. verify the IdP's group configuration step by step

Provisioning Reaches the Wrong Tenant​

This is a high-risk issue and should stop rollout immediately.

Likely causes:

  • wrong enterprise hostname
  • copied base URL from another environment
  • token created in one tenant but reused elsewhere

Do not continue rollout until the environment and tenant targeting are unambiguous.

Token Rotation Problems​

Common scenario:

  • a new token is created
  • the IdP still uses the old token
  • tenant admins revoke the old token too early
  • provisioning silently stops

Safer rotation pattern:

  1. create the new token
  2. update the IdP
  3. run a connection test
  4. verify a real provisioning event
  5. revoke the old token

IdP-Specific Notes​

Okta​

Check:

  • the app template is the SCIM 2.0 header-auth style app
  • the API integration test passes
  • users or groups are actually assigned to the app
  • attribute mappings still produce userName and email the way you expect

Microsoft Entra ID​

Check:

  • provisioning mode is automatic
  • the tenant URL points to the right /scim/v2 base
  • the secret token field contains the current SCIM token
  • provisioning logs or provision-on-demand results match the pilot user you are testing

OneLogin​

Check:

  • the SCIM connection is enabled successfully
  • the provisioning tab is actually turned on
  • assignments are in place
  • OneLogin is using the token format you expect

SCIM Error Types​

When the response includes a scimType field, it indicates the specific SCIM error category:

scimTypeMeaning
invalidFilterFilter syntax is malformed
uniquenessDuplicate userName or externalId
invalidSyntaxRequest body parse error
invalidValueField value fails validation
noTargetResource not found for the operation
mutabilityAttempt to change an immutable field

Good Escalation Package for Support​

If you need help from the AxonFlow team, collect:

  • the tenant or organization identifier
  • the SCIM base URL you configured
  • the identity provider used
  • the failing operation type: create, update, deactivate, or group sync
  • approximate timestamp
  • HTTP status code
  • whether discovery succeeds
  • whether the token shows recent use in the portal

Avoid sending live tokens in support channels.

Last updated on