Skip to main content

SSO & SCIM Troubleshooting

This page covers common problems and how to use the activity log to diagnose them.

The activity log​

All SSO and SCIM events are recorded under Settings → Account → Identity → Activity. The log shows the last 7 days, filterable by event type.

Always-on events:

Event typeWhen it fires
sso_errorAnything that went wrong during sign-in
sso_presignup_rejectA user was blocked at pre-signup — typically SCIM is enabled and the user hasn't been provisioned yet, or SSO isn't enabled on the tenant
sso_user_createdA new Agility user was JIT-created on first SSO sign-in
sso_user_attributes_updatedAn existing user's name, phone, or roles were re-synced from IdP claims
scim_errorA SCIM request failed
scim_provisionA user was created or updated via SCIM
scim_deprovisionA user was deactivated via SCIM

Debug-only events (enable Log successful events (debug) to see these):

Event typeWhen it fires
sso_login_successA user successfully signed in via SSO (one event per sign-in, regardless of whether anything changed)
scim_readA SCIM read request with full request/response payload

Always-on events cover every mutation — user creates, attribute/role changes, SCIM writes, errors. Debug mode adds visibility into no-op sign-ins and SCIM reads, which are higher-volume and lower-audit-value. Turn debug off after go-live to keep the log readable.

Click any row in the table to expand it and see the underlying detail — claim values, request bodies, error messages, HTTP status codes.

SSO problems​

sso_presignup_reject — SCIM required, user not provisioned​

Cause: The tenant has SCIM enabled, and the user signing in does not yet exist in Agility. JIT user creation is disabled when SCIM is on.

Fix:

  • Make sure the user is assigned to the Agility app in your IdP.
  • Trigger a sync from your IdP (Okta and Entra usually run automatically every 40 minutes).
  • Check the Activity tab for a corresponding scim_provision event.
  • Have the user retry.

Users sign in but have no roles​

Cause: None of the IdP groups (or attribute values) sent by your IdP match any row in your role mapping table.

Fix:

  1. Enable Log successful events (debug) on the Activity tab.
  2. Have the user sign in again.
  3. Open the sso_login_success event (or sso_user_attributes_updated if roles changed) and inspect the claim values your IdP actually sent.
  4. Check that:
    • Your IdP is including a groups claim (or the attribute you configured).
    • The values match your role mapping table exactly — matching is case-sensitive.

Common gotchas:

  • Entra sends group object IDs (GUIDs) by default, not group names. The recommended fix is to switch to App Roles — see Set up Entra ID. As a quicker workaround, set the group claim's Source attribute to Cloud-only group display names (cloud-only Entra groups) or sAMAccountName (on-prem AD-synced groups). Pasting raw GUIDs into your role mapping table works for SAML and OIDC but does not work for SCIM tenants — SCIM matches groups by display name, not object ID.
  • Okta sends only the groups that match the filter in the Group Attribute Statement — if the filter is too narrow, expected groups won't appear.

given_name and family_name are missing or empty​

Cause: Your IdP isn't sending given_name / family_name claims under those exact names, or isn't sending them at all.

Fix:

  • Okta SAML: In Attribute Statements, add given_name → user.firstName and family_name → user.lastName.
  • Okta OIDC: Make sure the profile scope is granted; Okta sends given_name / family_name automatically in that scope.
  • Entra SAML: In Attributes & Claims, ensure given_name is mapped to user.givenname and family_name to user.surname.
  • Entra OIDC: Make sure the profile permission is granted with admin consent.

If your IdP can't be changed but does send the names under different claim names (e.g. firstName, lastName), contact your Agility account team — we can configure a per-tenant attribute mapping override.

"We couldn't sign you in" on the OTP step​

Cause: Either the wrong code was entered, the code expired (10 minutes), or the IdP discovery service is unreachable.

Fix:

  • Have the user request a new code and try again.
  • If the error mentions discovery, check the Activity tab for sso_error events; this usually indicates a misconfigured tenant SSO setting.

Multi-tenant user can't pick a tenant​

Cause: The user belongs to more than one SSO-enabled tenant. By design, they see a tenant picker after entering the OTP. They must pick one before being redirected to the IdP.

Fix: No action needed — this is expected. Confirm the user actually has access to the tenant they're trying to reach.

Test Connection passes but real sign-in fails​

Cause: The Test Connection button validates configuration without invoking your IdP — it checks that URLs are reachable, certificates parse, and the discovery document is well-formed. Real sign-in can still fail if:

  • The user isn't assigned to the Agility app in your IdP.
  • Your IdP rejects the redirect URI (typo in what you pasted, or extra trailing slash).
  • Your IdP doesn't actually send the claims Agility expects (see "Users sign in but have no roles").

Fix:

  1. Have a real user attempt to sign in.
  2. Check the Activity tab for sso_error events.
  3. Read the detail row — it includes the underlying error from the IdP or Agility's sign-in service.

SCIM problems​

SCIM requests return 401 Unauthorized​

Cause: The bearer token (API key) in your IdP's SCIM configuration is missing, expired, or doesn't match an active key.

Fix:

  • In Agility, go to Settings → Account → API Keys and confirm the key is still active.
  • If you've rotated keys, update the token in your IdP's SCIM connector.
  • For Okta: Provisioning → To App → Edit → API Token.
  • For Entra: Provisioning → Admin Credentials → Secret Token.

SCIM requests return 404 or wrong tenant​

Cause: The SCIM endpoint URL in your IdP is pointing at the wrong tenant ID, or includes a typo.

Fix: Copy the SCIM endpoint from the portal again — use the copy button on the SCIM tab. The URL must include your tenant's exact ID after /scim/v2/.

Users provision but with no roles​

Cause: Same root cause as the SSO version: SCIM isn't sending group memberships (or the configured attribute), or values don't match the role mapping table.

Fix:

  1. Enable debug logging on the Activity tab.
  2. Inspect a scim_read or scim_provision event after the next sync.
  3. Confirm the group/attribute values your IdP is sending.
  4. Adjust the role mapping table to match.

A user was removed in the IdP but still has access​

Cause: SCIM deprovisioning hasn't run yet, or the user was unassigned from the app without being deactivated.

Fix:

  • Trigger a manual SCIM sync from your IdP.
  • Check the Activity tab for a scim_deprovision event.
  • If the event doesn't appear, confirm your IdP is configured to send a deactivation (Okta: enable Deactivate Users under provisioning settings; Entra: ensure the user is unassigned from the app, not just removed from a group).

SAML signing problems​

"SAML validation failed: Invalid document signature"​

Cause (most common — Entra): Entra is signing only the outer SAML response and not the assertion inside it. Agility requires the assertion to be signed.

Fix (Entra):

  1. In your Entra enterprise application, open Single sign-on.
  2. In the SAML Certificates section, click the edit (pencil) icon at the top right.
  3. Change Signing Option from Sign SAML response to Sign SAML response and assertion.
  4. Leave Signing Algorithm at SHA-256.
  5. Save and retry sign-in.

Other causes worth checking:

  • The certificate pasted into Agility doesn't match the one the IdP is signing with (e.g. the IdP rotated keys after you configured Agility). Re-import the metadata URL to refresh the certificate.
  • The certificate is correct but truncated or has whitespace inside the Base64 body. Re-paste the certificate as a single contiguous Base64 block (PEM headers optional).
  • The IdP is signing with SHA-1 in an environment that requires SHA-256, or vice versa. Standardize on SHA-256.

Sign-in fails after IdP rotates the SAML certificate​

Cause: Your IdP started signing assertions with a new certificate, but Agility only has the old one.

Fix:

  • Before rotation, paste the next certificate into the Signing Certificates field in Agility using the + icon next to the certificate list. Agility accepts assertions signed by any of the configured certificates, so both old and new will work during the rollover window.
  • After your IdP cuts over, remove the old certificate.

If you missed the rotation window, simply re-import the metadata URL — Agility will fetch the current certificate from your IdP and replace the stored one.

Still stuck​

If you've worked through the above and SSO or SCIM still isn't working:

  1. Reproduce the failure with a single test user.
  2. Note the approximate timestamp of the attempt.
  3. Capture the relevant entry from the Activity tab (screenshot or copy the detail JSON).
  4. Open a support request and include the timestamp, tenant ID, user email, and the captured event detail.

We officially support Okta and Entra ID for both SSO and SCIM. Other standards-compliant IdPs may work but are best-effort.