> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/getting-started-guide/federation/troubleshooting.md). # Federation troubleshooting and recovery Diagnose and recover from a broken SAML federation, including lockout recovery. Symptom-first. Find your row, check the inspection column before changing anything, and prefer the safest correction listed. Provider-specific rows live on each journey page; these are the cross-cutting ones. ## Sign-in flow problems | Symptom | Likely cause | What to inspect | Safest corrective action | | --------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | Redirect loop between IdP and SP | ACS/reply URL wrong on one side, or the two sides disagree about the entity ID | Compare the SP's ACS URL and entity ID character-for-character on both sides; watch for `http` vs `https` and trailing slashes | Fix the mismatched value on the side that's wrong; re-test in a fresh private window | | "Invalid issuer" / audience rejection | Issuer or Audiences field doesn't equal what the other side sends | The assertion itself (see *Inspecting an assertion* below): compare `` and `` to the configured values | Correct the provider's Request Issuer / Audiences (OpenIAM IdP) or SAML Issuer Name (OpenIAM SP) | | Signature validation failure | Wrong, rotated, or regenerated certificate | Certificate expiry dates on both sides; whether someone clicked *Generate a new key* recently | Re-exchange the current certificate (re-import metadata where supported); never regenerate keys to "fix" validation | | Assertion rejected as expired / not yet valid | Clock skew | NTP on the OpenIAM host (`chronyctl`/`timedatectl`) and the counterpart's time; OpenIAM enforces a \~10-minute validity window | Fix time sync; do not widen validity windows to compensate | | Works in one browser, not another | Cached session or SSO cookie confusion | Try a fresh private window before anything else | Clear the session; always test federation in private windows | | Logout doesn't end the session everywhere | Single logout not configured or not supported by the counterpart in that direction | Whether an SLO URL is set on the provider; which side initiated logout | Treat SLO as best-effort in the POC; document the observed behavior rather than forcing it | ## Matching and authorization problems (authenticated, then failed) The key diagnostic skill: **where** did it fail? IdP login succeeded but the SP shows an error ⇒ authentication worked, *matching or authorization* failed. | Symptom | Likely cause | What to inspect | Safest corrective action | | -------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User not found (OpenIAM as SP) | NameID doesn't match exactly one OpenIAM user | The NameID value in the assertion vs. the user's email/login in OpenIAM; duplicates also fail (must match exactly one) | Align the IdP's NameID claim with the OpenIAM value; don't hand-edit users to chase a bad claim mapping | | Immutable-ID mismatch (Entra journeys) | NameID ≠ `onPremisesImmutableId` | `Get-MgUser -UserId -Property OnPremisesImmutableId` vs. the user's OpenIAM login | Fix the immutable ID on the test user ([OpenIAM as IdP for Microsoft Entra ID](/getting-started-guide/federation/openiam-idp-entra.md) step 2) — before federating, where possible | | Microsoft rejects after OpenIAM login, UPN-looking error | `IDPEmail` attribute ≠ UPN | The assertion's attribute statement; the user's UPN | Correct the IDPEmail attribute mapping on the OpenIAM provider | | "Not authorized" from OpenIAM after successful matching | User not entitled to the provider's resource | The user's roles; the role's Entitlements for the *Authentication provider* resource | Entitle via the role — that this gate exists is a feature, not a bug | | User not assigned to the application (Entra SP journey) | Enterprise app requires assignment | The app's *Users and groups* list | Assign the test user; keep "assignment required" ON during POCs | | Google user never reaches OpenIAM | SSO profile / app not applied to their OU or group | The profile assignment or the app's *User access* screen | Assign the test OU; remember group assignments override OU assignments | ## Inspecting an assertion safely Use a browser SAML tracer extension (e.g. "SAML-tracer") in the **private test window with a test user** — never capture a real user's session. Read three things: ``, the `` value and format, and the ``. That triple answers most rows above. Assertions contain personal data — don't paste captures into tickets without redacting. ## Recovery **Entra domain federation (journey 14) went wrong:** 1. Sign in with a **break-glass admin** (`*.onmicrosoft.com` account, not federated) at the Entra admin center or via `Connect-MgGraph`. 2. `Get-MgDomainFederationConfiguration -DomainId ` → `Remove-MgDomainFederationConfiguration -DomainId -InternalDomainFederationId `. 3. Reversion can take up to 2 hours; verify with `Get-MgDomain` (authentication type: managed) and a test sign-in. **Google SSO profile (journey 15) went wrong:** 1. A super admin signs in directly at `admin.google.com` — super admins bypass third-party SSO there by design. 2. Remove the profile assignment from the OU/group (or set to *None*); users revert to Google-credential sign-in. **OpenIAM SP journeys (16–17) went wrong:** deactivate the provider in OpenIAM — password login was never affected, so there is nothing to recover beyond removing the added path. **Confirming a rollback propagated:** always finish with a positive test — the affected test user signs in the pre-federation way in a fresh private window — not just the absence of the error. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/getting-started-guide/federation/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.