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.

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)
     • To force immediate provisioning, use the "Provision on Demand" button in Entra admin portal
     • Consider this timing when troubleshooting missing users or group memberships

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)

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

Additional Resources

• Audit Events Documentation
• SAML Configuration Guide
• OIDC Configuration Guide