> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://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](/admin-hub/account_settings/microsoft-entra-scim) 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)