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
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
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
- 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
- Redirect URI
- Token attributes
- Secret validity
8. Confirm Domain Allowlists
If your platform uses Allowed Domains or Login Domains:- Add all corporate email domains
- 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
10. Trace the Redirect Chain
To see where the failure happens:- App → IdP redirect
- IdP → App return
- Token validation
- 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
- 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 LogsShows:
- Success
- Failure
- Skipped
- Warning
- 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
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
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)
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
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