> 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/administration-guide/federation/federate-a-microsoft-entra-domain.md). # Federate a Microsoft Entra domain Route sign-in for every user in a verified Microsoft Entra domain to OpenIAM, align the immutable identity, and roll the domain back to managed authentication. ## What this is, and when you need it Microsoft 365 domain federation is **not** the same as adding one SAML enterprise application. It changes sign-in routing for every user whose UPN uses that verified domain, and it is configured in Microsoft Graph rather than in a SaaS admin panel. Do it when you want OpenIAM to own authentication for a whole Entra domain; add an ordinary `SAML_PROVIDER` instead when one application is in scope. This page is authentication only — what federation does **not** give you is at the end. ## At a glance | | | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **You will end up with** | One verified test domain whose UPNs redirect to OpenIAM for authentication and return to Microsoft with a matching immutable identity, and a recorded federation-configuration ID you can use to reverse it | | **Where** | Microsoft Graph, through the Microsoft Graph PowerShell SDK — **not** the OpenIAM Webconsole. The OpenIAM half is an ordinary [SAML identity provider](/administration-guide/federation/saml-identity-provider.md) | | **You need first** | A working `SAML_PROVIDER` for this trust; a non-production subdomain or disposable tenant; `Domain-InternalFederation.ReadWrite.All` plus a supported Entra administrator role; and **at least two cloud-only administrators on the original `*.onmicrosoft.com` managed domain** | | **Takes** | A day, including the immutable-identity work and a synchronization cycle to confirm it holds | | **Reversible** | Yes, with the recorded federation ID — and the order matters: return the domain to managed authentication **before** you disable the OpenIAM provider | {% hint style="danger" %} **The cloud-only administrators are the break-glass path, and they are the whole safety net.** A federated domain sends every one of its users to OpenIAM; if OpenIAM stops answering, nobody on that domain can sign in to Microsoft 365 at all. Keep at least two administrators whose UPNs sit on the original `*.onmicrosoft.com` managed domain, and confirm they authenticate directly before and after the change. {% endhint %} ## Before you begin Finish the OpenIAM half first: a `SAML_PROVIDER` whose issuer, signing certificate and algorithms are settled and tested — [OpenIAM as a SAML identity provider](/administration-guide/federation/saml-identity-provider.md). Every value Entra needs comes from it. **Use Microsoft Graph, not MSOnline.** Those modules are retired. Use the Microsoft Graph PowerShell SDK and the [Graph domain-federation API](https://learn.microsoft.com/en-us/graph/api/domain-post-federationconfiguration?view=graph-rest-1.0), and verify the permission set and cmdlet parameters against Microsoft's current documentation rather than a recipe — both change between module versions. ## Federate the domain {% stepper %} {% step %} ### Collect the four values from the OpenIAM provider | What Entra needs | Where it comes from | | -------------------------- | ------------------------------------------------------------------------------------------ | | Issuer | Attribute `1` **Request Issuer** on the `SAML_PROVIDER` | | Passive sign-in URL | `https:///idp/saml2/idp/login` | | Sign-out URL | `https:///idp/saml2/idp/logout` | | Public signing certificate | The certificate published at `https:///idp/saml2/idp/metadata/` | Take the certificate from the metadata document rather than from a file on someone's laptop — the metadata is what the provider is actually signing with. {% endstep %} {% step %} ### Inspect the domain before you change it {% code overflow="wrap" lineNumbers="true" %} ```powershell Connect-MgGraph -Scopes "Domain.Read.All","Domain-InternalFederation.ReadWrite.All","User.ReadWrite.All" Get-MgDomain -DomainId "" | Select-Object Id,AuthenticationType,IsVerified Get-MgDomainFederationConfiguration -DomainId "" | Select-Object * ``` {% endcode %} `IsVerified` must be true and `AuthenticationType` should read as managed. Record both — they are what you are reversing to. {% endstep %} {% step %} ### Confirm the cloud-only administrators still work In a private session, sign in to Microsoft 365 as each `*.onmicrosoft.com` administrator. Do this now, before the change, so that a failure afterwards is unambiguous. {% endstep %} {% step %} ### Create the federation configuration and record the ID Create it with `New-MgDomainFederationConfiguration`, supplying the OpenIAM issuer, the HTTPS sign-in and sign-out endpoints, SAML as the protocol, and the public signing certificate. Parameter names vary by module version — run `Get-Help New-MgDomainFederationConfiguration -Full` and read the current Graph schema rather than adapting a `Connect-MsolService` example. **Record the returned federation ID immediately.** It is the argument the rollback needs, and retrieving it afterwards is harder than saving it now. {% endstep %} {% step %} ### Align NameID and immutable identity For a synchronized or hybrid Entra user, the SAML subject OpenIAM emits must match the agreed Entra source anchor / `onPremisesImmutableId` contract. Microsoft commonly Base64-encodes a **binary** source anchor — `mS-DS-ConsistencyGuid` or, by design, `objectGUID`. **Base64-encoding the *****printable***** GUID string produces a different value that will not match**, and that single mistake accounts for most failed first attempts. 1. Retrieve the raw directory identifier and the existing `onPremisesImmutableId` for a known test user. 2. Convert using the same binary convention as the tenant's synchronization authority. 3. Store the raw and derived values separately, with provenance. 4. Configure `IDPNameIDResolver` on **this provider only** to emit the derived value. 5. Compare character for character, including case. 6. Re-test after a further synchronization cycle. Never rewrite a production source anchor to make one SAML test pass. That is a hybrid-identity migration, not a fix. {% endstep %} {% step %} ### Validate one UPN end to end Retrieve the domain and federation record again. Then, in a private session, enter one test-domain UPN and confirm the redirect to OpenIAM, the successful return to Microsoft, the correct user, the signing certificate, and matching audit events on both sides. Confirm the cloud-only administrators still authenticate directly. {% endstep %} {% endstepper %} ## Verification | What to check | How | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The domain is federated to the issuer you intended | `Get-MgDomain -DomainId ""` reports a federated authentication type, and `Get-MgDomainFederationConfiguration` names your issuer and sign-in URL | | The redirect actually reaches OpenIAM | Enter a test-domain UPN at the Microsoft sign-in page in a private session and confirm the browser lands on OpenIAM | | The immutable identity matches | Compare the `NameID` in the assertion, in a SAML tracer, with the test user's `onPremisesImmutableId` — character for character, including case | | OpenIAM saw the request | A `SAML_IDP_PROCESS_SAML_REQUEST` audit event for that sign-in. See [Audit actions and retention](/administration-guide/reference/audit-actions-and-retention.md) | | The break-glass path survives | Each `*.onmicrosoft.com` administrator still signs in directly, after the change | | The rollback argument is recorded | You hold the federation-configuration ID returned at creation | ## When it goes wrong | Symptom | Cause | Fix | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Entra redirects to OpenIAM but rejects the returning user | The NameID does not match the tenant's `onPremisesImmutableId` — usually the printable GUID was Base64-encoded instead of the binary anchor | Fix the derivation. Never switch to email as an improvised immutable key | | Nobody on the domain can sign in and there is no way to fix it | The cloud-only administrators were never established, or their UPNs are on the federated domain | This is the reason for the danger notice above. Recovery is a Microsoft support matter, not an OpenIAM one | | The federation command is rejected | The consented scopes do not include `Domain-InternalFederation.ReadWrite.All`, or the signed-in account does not hold a supported Entra administrator role | Re-consent with the scope; Microsoft changes the required role between releases, so check their current documentation | | A parameter the recipe uses does not exist | Cmdlet parameter names vary by Graph module version | `Get-Help New-MgDomainFederationConfiguration -Full` and read the current schema | | SSO works but users and passwords do not synchronize | SAML is only the authentication trust | Configure the Graph connector and the password architecture separately | | Entra users are routed to an IdP that no longer answers | The OpenIAM provider was deleted or disabled before the domain was returned to managed authentication | Restore the provider, then reverse in the documented order below | ## Roll it back Use the recorded ID: {% code overflow="wrap" %} ```powershell Remove-MgDomainFederationConfiguration ` -DomainId "" ` -InternalDomainFederationId "" ``` {% endcode %} Then verify the domain has returned to managed authentication with `Get-MgDomain`, and confirm a test-domain UPN authenticates at Microsoft directly — **before** you disable or delete the OpenIAM provider. Delete the provider first and Entra users stay routed to an IdP that no longer answers. Retain the redacted metadata, certificate fingerprints and the audit events from both sides. Never a private key. ## What federation does not give you, and what to record Three designs get conflated here, and only the first is on this page. **SAML federation** redirects authentication to OpenIAM and returns a signed assertion. **Account lifecycle** creates, updates and disables Entra users through a Microsoft Graph connector, Entra Connect / Cloud Sync, or another owned process, and is configured as a managed system — [Connect applications and automate lifecycle](/administration-guide/lifecycle.md). **Password ownership and writeback** follows your directory architecture; SAML synchronizes no passwords. Do not promise provisioning or password writeback because SSO works. Keep a record of all of this, because it is what makes the next certificate rotation a maintenance task rather than an incident: the verified domain and its authentication type before the change; the OpenIAM issuer, the active and passive sign-in URLs, the sign-out URL and the public signing certificate; the Graph tenant, administrator, consented scopes and module version; the returned federation-configuration ID; one test UPN and its expected immutable identity value; and the exact removal command. ## Related * [OpenIAM as a SAML identity provider](/administration-guide/federation/saml-identity-provider.md) — the provider this depends on, and its rollback order * [Every SAML identity provider attribute, with its shipped default](/administration-guide/federation/saml-identity-provider/saml-identity-provider-reference.md) — `IDPNameIDResolver` and the NameID attributes * [Connect applications and automate lifecycle](/administration-guide/lifecycle.md) — Entra account lifecycle, which federation does not provide *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # 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/administration-guide/federation/federate-a-microsoft-entra-domain.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.