> 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/openiam-sp-entra.md). # Entra ID as IdP for OpenIAM Let users sign in to OpenIAM with their Microsoft Entra ID credentials. **Goal:** users sign in to OpenIAM's portals with their Microsoft Entra credentials, via an Entra enterprise application.\ **Time:** 45–75 minutes.\ **What this proves:** OpenIAM consumes Entra assertions and matches them to existing users; SP- and IdP-initiated flows both work; nothing else changes.\ **Prerequisites:** [shared prerequisites](/getting-started-guide/federation.md); Entra rights to create an enterprise application (e.g. Cloud Application Administrator). This is the lowest-risk journey — it *adds* a sign-in path; password login is untouched throughout. ## Values worksheet | Name | Example | Yours | | ------------------------------------------ | ----------------------------------------------------------------- | ----- | | Entity ID you choose for OpenIAM-as-SP | `openiam-poc-sp` | | | OpenIAM ACS / reply URL | `https:///idp/saml2/sp/login` | | | OpenIAM SP sign-on URL | `https:///idp/saml2/sp/login?issuer=openiam-poc-sp` | | | Provider ID (after step 2) | `3014` | | | Test user (exists in both; matching email) | `fedtest3@poc.example.com` | | ## Safety checks {% hint style="warning" %} Low blast radius, two rules anyway: use a **test-scoped enterprise app with explicit user assignment** (never "assignment not required" during a POC), and keep a working password-login admin session open in a second browser — the rollback is simply deactivating the provider. {% endhint %} {% stepper %} {% step %} **Create the enterprise application in Entra** Entra admin center → **Enterprise applications → New application → Create your own application** → non-gallery. Then open **Single sign-on** and select **SAML**:
The Entra enterprise application Single sign-on page, with SAML offered as the sign-on method alongside a disabled option
Set the Basic SAML Configuration from the worksheet: | Entra field | Value | | ---------------------- | ----------------------------------------------------------------------- | | Identifier (Entity ID) | `openiam-poc-sp` — becomes the **SAML Issuer Name** on the OpenIAM form | | Reply URL (ACS) | `https:///idp/saml2/sp/login` | | Sign on URL | `https:///idp/saml2/sp/login?issuer=openiam-poc-sp` | | Logout URL | `https:///idp/saml2/sp/logout` |
The Entra Basic SAML Configuration and User Attributes and Claims panels, showing the identifier, reply, sign-on and logout URLs and the five claim mappings
Set the NameID claim to the identifier that matches your OpenIAM users — for the POC contract below, **user.mail** (or UPN, if your OpenIAM emails equal UPNs). **Assign the test users to the app** — an unassigned user is stopped by Entra before OpenIAM ever sees them. Download the signing certificate (**.pem**) or copy the *App Federation Metadata Url*. {% endstep %} {% step %} **Create the SAML Service Provider in OpenIAM** **Access Control → Authentication Providers** → create a new provider → type **SAML Service Provider**. Fastest: download the Entra federation metadata XML (from the App Federation Metadata URL) and use **Import from Identity Provider Metadata**. The provider must end up with: | Field | Value | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Provider Name | `Entra login POC` | | Linked to Managed System | default OpenIAM managed system (incoming NameID is matched here — see step 3) | | SAML Issuer Name | `openiam-poc-sp` (must equal the Entra Identifier exactly) | | Sign-in page URL | the Entra **Login URL** from the app's SAML panel (the AuthnRequest is sent here) | | SSO Binding | POST (the default; note request signing is only supported with POST) | | Name ID Format | Email Address (goes into the AuthnRequest's NameIDPolicy; matches the claim you set in step 1) | | Want Assertions Signed | on (Entra signs assertions by default) | | Signature section | upload the Entra **.pem** certificate as the *Public Key for Validating Signatures* (already done if you imported metadata) | | Authentication policy / password policy | select your defaults | | Just-in-time provisioning groovy script | **leave empty** for the POC — with no script, unknown users are rejected, which is exactly what step 4's negative test proves. (Setting a JIT script later is how you auto-create users on first SSO login.) |
The Signature and Name ID sections of the OpenIAM SAML service provider form, showing the validation and signing key controls and the Name ID format
**Entitle the test users to this provider's resource** via a role (see the [chooser](/getting-started-guide/federation.md)) — OpenIAM refuses SSO for authenticated-but-unentitled users, which is a feature, and one of your negative tests. {% endstep %} {% step %} **Understand the match** OpenIAM matches an incoming assertion to a user like this: with **Email Address** NameID format, the NameID value is looked up against user email addresses (it must match exactly one user), then resolved to that user's login on the provider's linked managed system. So the POC contract is: *Entra sends user.mail → equals the OpenIAM user's email → user has a login on the linked managed system.* Verify all three for `fedtest3` before testing. **Authentication succeeded but matching failed** looks like: Microsoft login works, OpenIAM shows an error — the troubleshooting table tells them apart. {% endstep %} {% step %} **Validate** * **SP-initiated:** private window → `https:///idp/saml2/sp/login?issuer=openiam-poc-sp` → redirected to Microsoft → authenticate → land in SelfService. * **IdP-initiated:** launch the app from the user's `myapps.microsoft.com` portal. OpenIAM accepts unsolicited assertions (the provider is resolved from the assertion's audience), with one caveat: not with encrypted assertions — if you enable assertion encryption, use SP-initiated only. **Negative tests:** (a) an Entra user **not assigned** to the enterprise app → blocked by Microsoft; (b) an assigned Entra user with **no matching OpenIAM user** → clean OpenIAM rejection, no half-created session; (c) a matched but **un-entitled** user → OpenIAM authorization error. Three different failure points — capture all three. {% endstep %} {% endstepper %} ## Evidence to capture Both successful flows (screenshots), the three negative-test errors, the provider configuration page, and the Entra app's assignment list. ## Rollback Deactivate (or delete) the OpenIAM provider — password login was never affected. Delete or unassign the Entra enterprise app. Nothing else to unwind. ## You know this worked when… {% hint style="success" %} `fedtest3` reaches SelfService via Microsoft credentials both SP- and IdP-initiated, and each of the three negative tests fails at its expected gate. {% endhint %} ## If it failed | Symptom | Likely cause / where to look | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Entra error before any Microsoft login | User not assigned to the enterprise app | | Loop between Microsoft and OpenIAM | Reply URL ≠ `/idp/saml2/sp/login`, or Identifier ≠ SAML Issuer Name | | Microsoft login OK, OpenIAM error | Matching: NameID value doesn't equal exactly one user's email, no login on the linked managed system, or user not entitled to the provider resource | | Signature validation failure | Wrong/rotated Entra certificate — re-import the current metadata | | Works SP-initiated, fails from myapps | Assertion encryption enabled — unsolicited flows can't resolve the provider; test SP-initiated or disable encryption | More: [Federation troubleshooting and recovery](/getting-started-guide/federation/troubleshooting.md). Next: [Google as IdP for OpenIAM](/getting-started-guide/federation/openiam-sp-google.md). --- # 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/openiam-sp-entra.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.