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

​

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

​

5. Entra SCIM Setup Tips (From Original Doc)

​

✔ Separate SSO and SCIM Applications

Avoid mixing them in one app.

​

✔ Attribute Mapping & Precedence

• Ensure attributes like CustomSSO exist
• Set precedence correctly (2)
• Ensures SCIM values override local values when appropriate

​

✔ Notifications

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

---

​

6. 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