SSO & SCIM Troubleshooting Guide

This guide helps you quickly identify and resolve the most common SSO and SCIM configuration issues across Entra (Azure AD) and Okta.

1. SSO Setup Best Practices

1. Use the Correct App Types

Entra (Azure AD):

• Use a Web Application Registration for SSO.
• Use a separate Enterprise Application for SCIM provisioning.
• Avoids mixed configurations and permission bleed between SSO and SCIM.

2. Assign Users and Groups

Make sure the correct users and groups are assigned to:

• The SSO Enterprise Application
• The App Registration (when relevant)
• The SCIM Enterprise Application

Common symptom:
Unassigned users fail with AADSTS50105 (“User not assigned to application”).

3. Unique Tenant Routing

If you manage multiple tenants:

• Give each SSO app a unique Display Name
• Ensure the tenant identifier is unique
• Prevents requests from being routed to the wrong tenant

This affects the generated redirect URL.

4. Verify IdP Login URL + Redirect/Callback URI

Login URL

• For Okta, the tile link should point to your product’s main console URL, not a configuration page.

Redirect / Callback URI

Must match exactly, including:

• Scheme (https://)
• Host
• Path
• Case sensitivity
• Trailing slashes

If mismatched:

• 503 errors
• Redirect loops
• SSO succeeds in metadata test but fails during login

5. Verify Logout URL

Incorrect logout URLs can cause:

• Infinite logout loops
• “Bounced” sessions

6. Diagnose 502 vs 503 vs Redirect Loops

502 Error

Typically caused by:

• Invalid client ID
• Wrong or expired client secret
• Secret lifetime expired in Entra (rotate secrets as needed)

503 or Redirect Loop

Usually caused by:

• Redirect/Callback URI mismatch
• Tenant misrouting
• Wrong login/logout URL

Token validation failures

Look for:

• Azure errors 50008, 50011, etc.

7. Check Successful Discovery/Configuration Behavior

After a correct OIDC metadata discovery or connection test:

• Discovery values should auto-populate
• Hidden fields should become visible
• Values should reflect your IdP’s configuration

If discovery succeeds but login does not, check:

• Redirect URI
• Token attributes
• Secret validity

8. Confirm Domain Allowlists

If your platform uses Allowed Domains or Login Domains:

• Add all corporate email domains (the part after @ in user email addresses, e.g., yourcompany.com)
• Do not include the @ symbol — enter yourcompany.com, not @yourcompany.com
• Otherwise users may not be routed to SSO correctly

9. Maintain a Break-Glass Local Admin

Keep one admin with:

• A non-SSO domain
• Local authentication

Ensures access if SSO becomes misconfigured.

10. Trace the Redirect Chain

To see where the failure happens:

• App → IdP redirect
• IdP → App return
• Token validation

Collect:

• IdP sign-in logs
• Browser HAR file
• Azure error codes
• Okta system logs

11. Required JIT Attributes

For Just-In-Time user creation:
Your IdP must send:

• First Name
• Last Name
• Email

Missing attributes →

• Login succeeds but profile incomplete
• JIT provisioning fails entirely

---

2. Entra (Azure AD) – Specific Guidance

Where to Check SSO + Assignments

Entra Admin Center → Enterprise Applications

• Verify SSO method
• Confirm user/group assignments
• Review Redirect URIs
• Check Certificate/Secret expiration

Client Secret Management

• Ensure the secret matches the one expected by your platform
• Rotate secrets proactively before expiration
• Replace expired secrets in both Entra and the product

SCIM Provisioning Logs

Entra → Enterprise Apps → Provisioning → Provisioning Logs
Shows:

• Success
• Failure
• Skipped
• Warning

Look for:

• Attribute mapping issues
• Unsupported values
• Missing attributes
• Incorrect source of authority

---

3. Okta – Specific Guidance

System Logs

Okta Classic:
Dashboard → System Logs

Shows:

• Provisioning errors
• SCIM attribute issues
• Token failures
• Create/update/link/deactivate errors

Provisioning Errors

Common root causes:

• Invalid attribute mapping
• Unsupported data types
• Incorrect SCIM token
• Incorrect SCIM base URL
• “Automatic provisioning failed” messages

You can retry tasks via Tasks and fix mappings before rerunning.

Assignment Errors

If users are assigned incorrectly:

• Okta shows attribute validation failures
• User fails authentication or provisioning

---

4. SCIM Troubleshooting (All IdPs)

1. Required SCIM Attributes (Your SCIM API Expects These)

• First Name
• Last Name
• Email Address
• Manager
• External ID

Missing or incorrect types = create/update failures

2. SCIM Provisioning Logs (Use These First)

Entra → Provisioning → Provisioning Logs

Okta → System Logs & Tasks

Logs show:

• Create, Update, Skip, Fail
• Attribute-level reasons
• Mapping errors
• Role mismatches

3. Validate SCIM Tenant URL

Must match your environment exactly.

Your document included:

{environment_base_url}/auth/realms/airia/org/{client_guid}/scim/v2

Common mistakes:

• Missing /v2
• Wrong tenant ID
• Wrong environment (Dev vs Prod)

Incorrect URL → 404 or failed connection test

4. Validate SCIM Access Token

• Ensure token is correct
• Ensure token has not expired
• Regenerate and re-paste into IdP if needed — see Section 6: Recovering from a SCIM 401 Unauthorized Error below for the full step-by-step procedure for Entra and Okta

5. Attribute & Data Model Alignment

Common issues:

• Unsupported data type
• Invalid role value
• Invalid manager reference
• Duplicate email
• Missing required fields

Fix mapping in IdP → provisioning succeeds on next cycle.

6. Understand SCIM Retry Cycles

Entra ID

• Automatically retries failed operations in future sync cycles
• After fixing an issue, wait for next cycle OR
• Unassign → wait → reassign user/group

Airia synchronizes SCIM changes on a 10-minute interval. After provisioning or updating users in your IdP, allow up to 10 minutes for changes to appear in the Airia console. Your IdP provisioning logs may show success before Airia has completed its sync cycle — this is expected behavior.

5. Entra SCIM Setup Tips (From Original Doc)

✔ Separate SSO and SCIM Applications

Avoid mixing them in one app.

✔ Notifications

Set a notification email under Provisioning settings to receive SCIM failure alerts.

---

6. Recovering from a SCIM 401 Unauthorized Error

If your IdP’s provisioning logs report a 401 Unauthorized response from the Airia SCIM endpoint, the most likely cause is an expired or invalidated SCIM access token. SCIM access tokens are valid for 180 days. Once a token expires, your IdP can no longer push user and group changes to Airia until a new token is generated in Airia and pasted into your IdP’s provisioning configuration.

End-user SSO login is not affected by this error. The 401 is isolated to the SCIM provisioning flow between your IdP and Airia. Users who can already sign in will continue to be able to do so.

Symptoms

• Entra (Azure AD): Provisioning Logs show 401 Unauthorized from the Airia SCIM endpoint. After repeated credential failures, Entra automatically places the provisioning job into “quarantine.”
• Okta: System Logs show provisioning failures with a 401 response; Test API Credentials on the Provisioning tab fails.
• Newly assigned users, group changes, or de-provisioning actions in your IdP do not appear in Airia.

Part 1: Generate a new SCIM token in Airia

1. Log in to the Airia Platform as a Platform Admin or Security Admin.
2. In the left sidebar, click Settings.
3. Open SSO & Provisioning.
4. Confirm the SSO toggle is enabled. The SCIM section appears below the SSO configuration.
5. Enable the SCIM 2.0 toggle.
6. Click Generate Key next to the Access Token field.
7. The following will populate:
   • SCIM Endpoint — the URL to configure in your IdP
   • Access Token — the newly generated bearer token (visible in plain text)
   • Token Expiry — expiration date and days remaining (approximately 180 days)
8. Click the copy icon next to the Access Token field to copy it. A “Copied to clipboard” toast confirms the copy.
9. Click the copy icon next to the SCIM Endpoint field to copy the URL.

Copy the Access Token immediately. Once you navigate away from the SSO & Provisioning page, the token is masked and cannot be revealed again — you would need to regenerate a new one. Update your IdP promptly to minimize sync downtime.

Part 2: Update the token in your IdP

Detailed steps are provided below for Microsoft Entra ID and Okta, the most commonly used identity providers. If you use a different SCIM-compatible IdP, follow your provider’s documentation for updating SCIM provisioning credentials — the two values you need are the same regardless of IdP:

• The SCIM Endpoint URL from Part 1 (sometimes labeled “Tenant URL,” “Base URL,” or “SCIM connector base URL” in your IdP)
• The Access Token from Part 1 (sometimes labeled “Secret Token,” “Bearer Token,” or “API Token” in your IdP)

After updating, run your IdP’s connection test, save the configuration, and resume provisioning if it was paused.

Part 2A: Update the token in Microsoft Entra ID

1. Sign in to the Microsoft Entra admin center at entra.microsoft.com.
2. Navigate to Entra ID → Enterprise apps.
3. Select your Airia application from the list.
4. In the left menu, click Provisioning.
5. Expand the Admin Credentials section.
6. Update the fields:
   • Tenant URL — paste the SCIM Endpoint URL from Part 1, step 9
   • Secret Token — paste the Access Token from Part 1, step 8
7. Click Test Connection and wait for the success confirmation.
8. Click Save at the top of the page.
9. If provisioning was paused or quarantined, click Restart provisioning on the Provisioning page to resume.

Entra automatically places provisioning into “quarantine” after repeated credential failures, with retries at 6, 12, and 24 hours before settling into a once-daily cadence. If the credential issue is not resolved within 4 weeks, the provisioning job is automatically disabled. Update the token promptly to avoid having to recreate the job.

Part 2B: Update the token in Okta

1. Sign in to the Okta Admin Console.
2. Navigate to Applications → Applications.
3. Select your Airia application from the list.
4. Click the Provisioning tab.
5. Under Settings → Integration, click Edit.
6. Update the fields:
   • SCIM 2.0 Base URL — paste the SCIM Endpoint URL from Part 1, step 9
   • OAuth Bearer Token — paste the Access Token from Part 1, step 8
7. Click Test API Credentials and wait for the success confirmation.
8. Click Save.
9. Verify sync is working from the Assignments or Push Groups tab — successful pushes should resume on the next sync cycle.

Preventing recurrence

• Set a calendar reminder before the 180-day expiry of each SCIM token.
• Watch for the expiry warnings on the SSO & Provisioning page:
  • Yellow when fewer than 30 days remain
  • Red when fewer than 7 days remain
• Refer to our SCIM setup guide for IdP-side configuration best practices.

Allow up to 10 minutes after updating the token for the next SCIM sync cycle to complete and for changes to appear in the Airia console.

---

7. Quick Diagnostic Checklist (Complete + Preserved)

SSO

• Redirect/Callback URI exact match (case + trailing slash)
• Logout URL correct
• Users/groups assigned
• Client ID + Secret valid, not expired
• Allowed domains configured
• Unique app display names for multi-tenant setups
• Break-glass admin available
• Successful discovery values populated
• Okta tile points to main console URL

SCIM

• Tenant URL valid (.../scim/v2)
• SCIM token correct + active
• Required attributes mapped and valid
• Attribute types align with expected model
• No duplicate emails
• Review Provisioning Logs for skipped/failed entries
• Fix mappings and retry or allow next cycle
• Role or data type mismatches corrected
• Okta System Logs checked for create/update/link errors
• If you see 401 Unauthorized in provisioning logs, regenerate the SCIM token (see Section 6 above)