How do I troubleshoot SCIM user sync failures?

Here’s a practical SCIM user sync troubleshooting checklist you can use for most IdP/SaaS setups (Okta, Entra ID/Azure AD, OneLogin, Ping, etc.).

1) Identify where the failure happens

Break SCIM into stages:

• Provisioning test / connection test fails → likely authentication, endpoint, or TLS issue.
• Users create/update but attributes are wrong → likely schema/mapping issue.
• Users don’t deprovision → likely filtering, permissions, or lifecycle rule issue.
• Intermittent failures → rate limiting, timeouts, duplicate conflicts, or transient API issues.

2) Check the SCIM basics

Verify these first:

• Base URL is correct
  • Usually something like: https://your-domain/scim/v2
• Auth token / bearer token is valid
  • Not expired, not rotated, copied correctly
• TLS/SSL certificate is valid
  • No invalid chain, hostname mismatch, or self-signed cert issues unless explicitly allowed
• SCIM version and endpoints are supported
  • Common endpoints:
    • GET /ServiceProviderConfig
    • GET /Schemas
    • GET /ResourceTypes
    • POST /Users
    • PATCH /Users/{id}
    • GET /Users?filter=...
• Content-Type and Accept headers
  • Usually application/scim+json

3) Check logs on both sides

On the IdP side

Look for:

• HTTP response code
• Error body returned by the SCIM app
• Request ID / correlation ID
• Which user and operation failed

On the SCIM server / app side

Look for:

• Auth failures
• Validation errors
• Duplicate user conflicts
• Schema parsing errors
• Rate limiting
• Timeouts / upstream dependency failures

If available, enable debug or audit logging for SCIM requests.

4) Interpret HTTP status codes

Common meanings:

• 200 / 201 / 204: success
• 400 Bad Request: malformed payload, invalid attribute, bad filter
• 401 Unauthorized: bad token, missing auth, expired token
• 403 Forbidden: authenticated but not allowed
• 404 Not Found: wrong endpoint, missing user/resource
• 409 Conflict: duplicate user or uniqueness constraint
• 415 Unsupported Media Type: wrong content type
• 429 Too Many Requests: rate limiting
• 500 / 502 / 503 / 504: server or upstream problem

5) Validate the SCIM payload

A very common issue is a schema mismatch.

Check:

• Required attributes are present
• Attribute names match what your app expects
• userName is unique and stable
• Emails, names, and external IDs are formatted correctly
• PATCH operations are supported if the IdP uses PATCH for updates
• Multi-valued attributes are handled correctly
• Booleans and enums are accepted in the expected format

Example things that often break:

• userName sent as email, while your app expects an internal username
• emails array missing primary: true
• active not supported or ignored
• IdP sending PATCH, but your SCIM server only supports PUT

6) Check provisioning rules and filters

Sometimes sync fails because the user isn’t actually selected for provisioning.

Confirm:

• The user is assigned to the app in the IdP
• Group-based assignment is correct
• Filters exclude the user
• Deprovisioning rules are enabled
• Scope includes the right population

7) Look for duplicate identity problems

SCIM often needs a stable mapping between the IdP and your app.

Check:

• Does your app use id or externalId to map users?
• Has the user been created manually before SCIM tried to create them?
• Are there duplicate emails or usernames?
• Did the target account already exist under a different identifier?

A frequent failure is:

• Create succeeds once, then updates fail because the IdP can’t reconcile the existing account with its SCIM identifier.

8) Confirm PATCH vs PUT support

Different IdPs use different update methods.

• Some send PATCH for incremental updates
• Some expect PUT for full replacement
• Your SCIM endpoint should support whichever your IdP uses, or the integration settings should match

If updates fail but creates work, this is a strong suspect.

9) Test with cURL or Postman

Reproduce the issue manually to isolate the problem.

Example:

curl -X GET "https://your-domain/scim/v2/Users" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/scim+json"

Try:

• GET /ServiceProviderConfig
• POST /Users with a minimal valid body
• PATCH /Users/{id} if supported

If manual calls work but the IdP fails, the issue is likely in mappings or IdP configuration.

10) Check rate limits and retries

If many users fail at once:

• Your SCIM service may be rate limiting
• The IdP may be retrying after timeouts
• Bulk sync may be hitting API or DB limits

Look for:

• 429s
• Backoff behavior
• Long response times
• Partial failures in batches

11) Review deprovisioning / suspend behavior

Deprovisioning can fail if:

• Your app does not support active=false
• The IdP uses delete, while your app expects deactivate
• The account is protected or linked to another system
• A downstream system blocks removal

12) Validate SCIM response format

Your service should return proper SCIM responses, including:

• schemas
• id
• meta
• userName
• Correct HTTP status codes
• Location header on create, if applicable

Example create response should generally be:

• 201 Created
• JSON resource for the created user
• id populated

13) Common root causes by symptom

“Test connection failed”

• Wrong URL
• Invalid token
• TLS/cert issue
• Endpoint not reachable

“User create failed with 400”

• Bad schema
• Missing required field
• Invalid attribute value

“User create failed with 409”

• Duplicate user / username / email
• Existing account conflict

“User update failed”

• PATCH not supported
• Read-only attribute being modified
• Identifier mapping mismatch

“User not deactivated”

• Deprovisioning rule disabled
• App doesn’t support active
• Wrong lifecycle action mapping

14) If you control the SCIM server

Make sure your implementation supports:

• Filtering by userName and externalId
• Pagination
• PATCH operations
• Proper SCIM schemas
• Unique indexing for username/email if required
• Idempotent create/update behavior where possible

Also ensure:

• Timeouts are reasonable
• Errors return helpful SCIM error messages
• Logs include request IDs and payload summaries
• Secrets are rotated safely without breaking the IdP config

15) Gather info before escalating

If you need vendor support, collect:

• IdP name and version
• SCIM endpoint URL
• Failing user(s)
• Timestamp of failure
• HTTP status code and response body
• Request ID / correlation ID
• Whether create/update/delete failed
• Payload sample with sensitive fields redacted

---

If you want, I can also give you:

1. a step-by-step SCIM debug flowchart, or
2. troubleshooting steps for a specific IdP like Okta or Microsoft Entra ID.