SSO Troubleshooting

This guide helps you troubleshoot SSO configuration issues that your customers might encounter when configuring SSO for their tenant. Follow these steps to identify and resolve common SSO problems.

SSO Error Codes

These errors can occur during an SSO login, when Descope federates to the tenant's identity provider (IdP). Codes marked Internal indicate a server-side issue; if you hit one repeatedly, contact support with the code and a timestamp.

SSO Login and Federation

Common fixes:

• E061016: add the redirect URL to the SSO application's approved list in your SSO settings.
• E061206: set a Post Authentication Redirect URL (project or tenant). See IdP-initiated.
• E062604 / E062606: bad or stale SAML key/cert — refresh IdP metadata/cert or fix SP keys. See Certificate and metadata rotation and SAML Signing and Encryption Keys.
• E062014: enable JIT provisioning, or pre-provision the user (SCIM or invite).
• E062020 / E062021 / E062023: check the email and domain the IdP returns against the tenant's SSO domain and the user's app assignment. See SAML Security → Assertion validation.
• E062016 / SchemaDoesNotExist: define an FGA schema before using SSO → FGA group maps. See SSO mapping → FGA.
• E113201: FGA mappable helpers need valid FGA-mappable SAML settings and the AllowFGAMappings flag.
• Internal codes: retry once; if it persists, contact support with the code and a timestamp.

SCIM (Directory Sync)

These errors happen during SCIM operations at the user layer, when Descope provisions users to or from a tenant's SCIM-enabled application. They're returned as HTTP 400.

Step 1: Check Audit Logs

The Audit and Troubleshoot page in the Descope Console provides detailed information about SSO-related events. To effectively use audit logs for SSO troubleshooting:

1. Review our SSO Audit Events documentation to understand available events
2. Filter events using the keyword "SSO" in the search bar
3. Focus on login events that contain SSO-specific fields:
   • SAML/OIDC response data
   • Group and role assignments
   • User provisioning details

Step 2: Common Issues and Solutions

SAML Configuration Issues

1. Metadata Mismatch

   • Verify the Descope ACS (Assertion Consumer Service) URL and Entity ID are copied correctly to the IdP
   • Verify the IdP metadata matches exactly

2. Certificate Issues

   • Ensure certificates are valid and not expired
   • Verify certificate format (Base64-encoded X.509)
   • Check if IdP requires signing

3. Callback URL Configuration

   • Verify the callback URL is correctly configured in your application settings
   • Ensure the URL matches the one registered in your SSO configuration
   • Check for any URL encoding issues or trailing slashes

4. Attribute Mapping Problems

   • Review attribute mapping configuration in SSO Setup Suite
   • Verify IdP is sending expected attributes
   • Check attribute names and formats match exactly

OIDC Configuration Issues

1. Endpoint Configuration

   • Verify all endpoint URLs are correct
   • Check authorization and token endpoint URLs
   • Confirm userinfo endpoint is accessible

2. Client Credentials

   • Verify Client ID and Secret are correct
   • Check if credentials have expired
   • Confirm redirect URIs are properly configured

3. Scope Configuration

   • Ensure required scopes are configured
   • Verify IdP is authorized for requested scopes
   • Check if custom scopes are properly formatted

User Attribute / Group Mapping Issues

User/Group mapping is one of the most common sources of SSO configuration problems.

Here's how to troubleshoot based on your Identity Provider:

1. General Group Mapping Issues

   • Verify the Group's Attribute Name matches exactly what your IdP sends
   • Check if groups are being sent in the SAML assertion or OIDC token
   • Ensure group names in the mapping match exactly (case-sensitive)
   • Review the Audit Logs to see what group data is being received

2. Microsoft Entra ID (Azure AD) Specific Issues

   • User attributes often come in URI format (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)
   • Common issues with email/login ID mapping:
     • Make sure you map the SAML Subject ID to either user.mail or user.userprincipalname. If the User Principal Name (UPN) is not the user's email address, use user.mail.
     • Check if the email format matches your application's requirements
     • Ensure the user has an email address in their contact details in Entra
   • For groups:
     • Enable "Security Groups" in token configuration
     • Use Object ID instead of Display Name for more reliable mapping
   • SCIM Provisioning timing:
     • By default, Entra only syncs users and groups every ~40 minutes (this interval is not configurable)
     • Disabled or deprovisioned users are often not pushed to Descope until Entra runs a cycle that includes them — or until you trigger Provision on Demand / a provisioning job manually
     • To force immediate provisioning (create, update, or disable), use Provision on Demand in the Entra admin portal
     • See SCIM with Azure and SCIM Best Practices

3. Okta Specific Issues

   Understanding Okta's Group System

   • Two separate group mechanisms exist in Okta:
     1. Push Groups - Control SAML/OIDC group assertions
        • Configure in the "Group Attribute Statements" section
        • Used for sending group membership in auth tokens
        • Can use regex matching (e.g., .* to match all groups)
     2. Assignments - Control SCIM provisioning
        • Found in the "Assignments" tab
        • Determine which users/groups get provisioned
        • Requires explicit assignment for provisioning
        • Use separate groups for SCIM vs SAML/OIDC push

   Troubleshooting Steps

   • Missing users in Descope:
     • Check if users are assigned to the application
     • Users in Push Groups but not assigned won't be provisioned
   • Group membership problems:
     • Verify "Group Attribute Statements" is enabled
     • Ensure groups are included in SAML assertion
     • Check group name matching is exact (case-sensitive)

SSO User Merging

When troubleshooting SSO user merging issues, see Merging SSO Identities.

SCIM Configuration Issues

SCIM troubleshooting depends on your specific setup. If you're using only SSO with JIT Provisioning, without SCIM, this section doesn't apply to you.

Scenario 1: SSO + SCIM with JIT Provisioning

When using both SAML/OIDC SSO and SCIM together with JIT enabled:

• Mapping Configuration: SCIM uses the same mapping configuration as SSO
• Login ID Consistency: Ensure login IDs are consistent across both protocols:
  • SAML: Login ID is the SAML NameID
  • OIDC: Login ID is the issuer by default (can be changed)
  • SCIM: Login ID is the username
• User Merging: SCIM follows the same merging rules as SSO authentication and is affected by the Convert Existing Users to SSO-only setting

Scenario 2: SCIM Only (No SSO)

When using SCIM without SSO, you still need to configure SSO group/attribute mapping:

• Group Mapping: Configure SSO group mapping even though you're not using SSO authentication
• Attribute Mapping: Only custom attributes need explicit mapping (standard attributes are covered by SCIM protocol)

Scenario 3: User Cannot Log In, Was Never Provisioned

This is the most common SCIM-related issue: SCIM is configured, JIT is disabled (as recommended), and a specific user (often a new hire) cannot log in. The failure can surface in one of two ways:

• Authentication is rejected by the IdP before Descope is reached. This is the typical case: the IdP rejects login for any user who is not assigned to the app.
• Authentication succeeds, but Descope returns a "user not found" style error. This happens when the customer uses different IdP applications for SSO and SCIM, and the user is assigned to the SSO app but not the SCIM app, so SSO works but no SCIM record exists in Descope.

Cause: In both cases, the IdP never provisioned this user to Descope. Provisioning is controlled by the IdP, not by Descope. A user is only pushed to Descope if they are assigned to the application on the IdP side representing Descope (an Enterprise Application in Azure, an app integration in Okta), either directly or as a member of a group that is assigned to the app. If the user was not in scope when SCIM was first set up and was never assigned afterward, the IdP will not push them, and Descope will have no record of them.

Diagnosis:

1. Open the Audit and Troubleshoot page and filter for SCIMEvent events scoped to the tenant.
2. Search for an event corresponding to the user (by email or login ID).
3. If no SCIMEvent exists for the user, the IdP has never pushed them. The fix is on the IdP side.

Resolution:

• In Azure: confirm the user is assigned to the Enterprise Application (directly or via an assigned group), then use Provision on Demand to push them immediately rather than waiting for the next 40-minute cycle.
• In Okta: confirm the user is in the Assignments tab of the application. Note that Assignments (which control SCIM provisioning) are separate from Okta's Push Groups (which push group objects via SCIM) and from Group Attribute Statements / OIDC claims (which control the groups sent in the SAML/OIDC authentication assertion). A user appearing in any of those does not mean they are assigned to the app.
• Ask the customer about their ongoing onboarding process: if they assign users one at a time, every new hire will hit this issue. Point them at SCIM Best Practices for the group-based assignment pattern.

General SCIM Troubleshooting

For all SCIM scenarios:

• Check SCIM logs for provisioning errors
• Ensure attribute mappings are consistent across all configurations
• Test with a sample user to verify proper provisioning and merging

Step 3: Using SAML Tracer

SAML Tracer is a browser extension that helps debug SAML authentication issues:

1. Installation and Setup

   • Install SAML Tracer in your browser
   • Enable the extension before testing SSO

2. Capturing SAML Traffic

   • Start SAML Tracer before initiating SSO login
   • Look for SAML Request and Response messages
   • Examine the raw SAML assertions

3. Common Patterns to Look For

   • Missing or malformed SAML assertions
   • Incorrect signature validation
   • Timestamp validation failures
   • Missing required attributes