Skip to main content

Microsoft Entra ID (SAML)

This page walks through federating Microsoft Entra ID into Prism using SAML 2.0, from an empty Entra tenant to a working sign-in. No prior SAML experience is assumed.

Two systems are involved, and each needs to be told about the other:

  • Prism is the Service Provider (SP). It publishes the three values Entra needs: an ACS (Reply) URL, an Entity ID, and a metadata descriptor URL.
  • Microsoft Entra ID is the identity provider (IdP). It publishes a sign-on URL, an issuer, and a signing certificate that Prism needs, all of them contained in one metadata document.

You will therefore switch between the two consoles. Keep both open in separate browser tabs.

info

For the field-by-field reference behind every value on the Prism side, see SAML 2.0 Provider.

What You Need​

  • The Cloud Application Administrator role in Microsoft Entra ID, or a higher role such as Application Administrator or Global Administrator. Creating an enterprise application and assigning users both require it.
  • Administrator access to the Prism Admin Portal.
  • A test user in Entra whose mail attribute is populated, and who already has a Prism account with the same email address.
caution

The test user's Prism account is not optional. Prism links a federated login to an existing account and never creates one, so a user who authenticates perfectly at Entra but has no Prism account is refused at the last step. Create the Prism account first, under Admin Portal > Users, and use the same email address as the Entra user's mail attribute.

Step 1: Copy Prism's Service Provider Values​

  1. In Prism, navigate to Admin Portal > Identity Providers.
  2. Click the SAML 2.0 tab, then click Add SAML IdP.
  3. Enter a Display Name, for example Contoso Entra. Prism derives the provider's alias from this name, and the alias appears inside the ACS URL.
  4. Copy all three Service Provider values shown at the top of the dialog:
    • ACS / Reply URL, ending in /broker/<alias>/endpoint
    • SP Entity ID, ending in /realms/<realm>
    • SP metadata descriptor, ending in /broker/<alias>/endpoint/descriptor

Leave this dialog open. You will come back to it in Step 7, and closing it discards the display name you just chose, which would change the alias.

warning

The values shown before you click Create are a preview. Prism assigns the final alias when the provider is saved, and appends a numeric suffix if the alias is already taken. Step 8 exists specifically to catch that case.

Step 2: Create the Enterprise Application​

  1. Sign in to the Microsoft Entra admin center or the Azure Portal.
  2. Go to Enterprise applications.
  3. Click New application.
  4. Click Create your own application.
  5. Enter a name, for example Prism SSO. This name is what users see in the Entra portal; it does not have to match Prism's display name.
  6. Select Integrate any other application you don't find in the gallery (Non-gallery).
  7. Click Create. Entra takes a few seconds to provision the application.
note

Use Enterprise applications, not App registrations. An app registration is the OAuth/OIDC surface; the SAML configuration you need lives on the enterprise application.

Step 3: Configure Basic SAML Configuration​

  1. In the new application, go to Single sign-on in the left-hand menu.
  2. Choose SAML as the single sign-on method.
  3. In the Basic SAML Configuration card, click Edit.
  4. Fill in exactly two fields, using the values you copied in Step 1:
Entra fieldPaste Prism's…
Identifier (Entity ID)SP Entity ID
Reply URL (Assertion Consumer Service URL)ACS / Reply URL
  1. Leave Sign on URL, Relay State, and Logout Url blank.
  2. Click Save, then close the edit panel.
caution

Entra matches both of these values character for character. The comparison is case-sensitive and trailing-slash-sensitive: .../endpoint and .../endpoint/ are two different Reply URLs, and so are https://Auth.example.com/... and https://auth.example.com/.... A mismatch produces AADSTS50011 at sign-in, with the URL Entra received quoted in the error. Copy and paste rather than typing, and do not let a text editor add a trailing newline or slash.

note

Sign on URL is deliberately blank. Populating it enables IdP-initiated sign-in, which Prism does not support. See Things Entra Does Differently.

Step 4: Check Attributes and Claims​

Entra populates a default claim set when the application is created. Two of those claims matter to Prism.

  1. In the Attributes & Claims card, click Edit.
  2. Confirm the following two rows:
Claim nameSource attributeUsed by Prism as
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressuser.mailThe user's email, which is how Prism matches the login to a Prism account
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameuser.userprincipalnameThe principal, the stable key that ties the federated identity to the Prism account
  1. If either row is missing or points somewhere else, click it and correct the source attribute, then Save.
warning

user.mail is empty for users who have no Exchange mailbox and for most B2B guest accounts, and an empty email claim means Prism cannot match the login to a Prism account. Before you test, check the test user's Contact information > Email in Entra. If it is blank, either:

  • populate the user's mail attribute in Entra (or in the on-premises directory that syncs into it), or
  • point the emailaddress claim at user.userprincipalname instead. That is acceptable when your UPNs are real, routable email addresses that match the Prism accounts.

Do not solve this by changing the principal claim to user.mail. The UPN is always present; user.mail is not, and a null principal fails the sign-in outright.

Step 5: Assign the Test User​

An Entra enterprise application only issues assertions for users assigned to it.

  1. Go to Users and groups in the application's left-hand menu.
  2. Click Add user/group.
  3. Select your test user and click Assign.
caution

A user who is not assigned to the application gets AADSTS50105 at sign-in ("the signed in user is not assigned to a role for the application"), even though their credentials are correct and everything else is configured properly. Assign every user or group that should be able to sign in.

Step 6: Copy the App Federation Metadata URL​

  1. Return to the Single sign-on page.

  2. Find the SAML Certificates card.

  3. Copy the App Federation Metadata Url. It looks like this, and contains an ?appid= query parameter:

    https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<application-id>

  4. Note the Thumbprint shown for the active certificate, and the Expiration date. You will confirm the thumbprint in the next step.

warning

Copy the App Federation Metadata Url from the SAML Certificates card, the one containing ?appid=. The tenant-wide federation metadata URL (the same URL without the appid parameter, which Entra also publishes) does not carry this application's token-signing certificate. Importing it produces a provider that looks configured but fails every signature check.

Step 7: Import the Metadata into Prism​

  1. Switch back to the Prism SAML dialog you left open in Step 1.
  2. Set the configuration source to Metadata URL.
  3. Paste the App Federation Metadata Url and click Import.
  4. Review what Prism filled in:
    • IdP Entity ID should read https://sts.windows.net/<tenant-id>/, including the trailing slash.
    • Single Sign-On Service URL should point at https://login.microsoftonline.com/<tenant-id>/saml2.
    • Signing Certificate should be populated. Compare the thumbprint Prism shows against the one Entra displayed in Step 6; they must be identical. A mismatch means the wrong metadata URL was imported.
    • Principal Type will be ATTRIBUTE and Principal Attribute will be the UPN claim. This is expected: Entra publishes no NameID format, so Prism applies its Entra rule rather than reading the principal from the NameID.
    • Email Attribute Name should be the emailaddress claim from Step 4.
  5. Click Create.
info

If Prism's servers cannot reach login.microsoftonline.com, use the Metadata XML file method instead: download the metadata document in a browser using the same ?appid= URL, then upload the file. Both methods produce an identical configuration.

Step 8: Re-check the Alias Prism Assigned​

After Create succeeds, Prism shows the Connection details dialog with the provider's final Service Provider values.

  1. Compare the ACS / Reply URL in this dialog against what you entered in Entra in Step 3.
  2. If they differ (the alias will have picked up a numeric suffix, saml-contoso becoming saml-contoso-1), go back to Entra, open Single sign-on > Basic SAML Configuration > Edit, replace the Reply URL with the value from this dialog, and Save.
warning

This is the single most common first-attempt failure. The alias cannot be known until the provider is saved, so the URL you pasted into Entra in Step 3 was a prediction. It is wrong whenever another identity provider already holds that alias, including when you are re-running this walkthrough after deleting a previous attempt with the same display name. The symptom is AADSTS50011, and the error message quotes the Reply URL Entra was given. Compare it against the Connection details dialog.

Step 9: Test the Sign-In​

  1. Open a private or incognito browser window. This matters: an existing Prism session or an existing Entra session will mask configuration problems and give you a false pass.
  2. Go to your Prism login page.
  3. Click the new SSO button, named after the display name you chose.
  4. Sign in as the test user.
  5. You should land in Prism, signed in as the Prism account whose email matches the test user's.

If the sign-in fails, read the error and work from SAML 2.0 Issues, which lists every AADSTS code you are likely to see here along with its cause.

Things Entra Does Differently​

Three Entra behaviors surprise people and are not misconfigurations. Read these before filing a bug.

IdP-initiated sign-in is not supported​

Prism only supports SP-initiated sign-in: the flow must start at the Prism login page, which sends the user to Entra and receives the assertion back. Prism does not accept an unsolicited assertion.

That means:

  • Entra's Test single sign-on button on the Single sign-on page will fail. It performs an IdP-initiated sign-in.
  • The My Apps portal (myapplications.microsoft.com) and the Microsoft 365 app launcher tile for this application will also fail, for the same reason.

Always test the way your users will actually sign in: start at the Prism login page.

Single logout is not configured​

Prism does not send a SAML logout request to Entra, and this is why Logout Url was left blank in Step 3. Signing out of Prism ends the Prism session only; the user's Entra session remains active, so clicking the SSO button again signs them straight back in without a credential prompt. To fully sign out, the user must also sign out of Microsoft.

The signing certificate expires after three years​

Entra issues the application's token-signing certificate with a three-year lifetime. When it expires, every sign-in through this provider fails with a signature validation error.

Entra emails the addresses listed under SAML Certificates > Notification Email Addresses at 60, 30, and 7 days before expiry. Prism does not fetch the certificate at login time (it is pinned in the provider configuration deliberately, so that a login never depends on an outbound call to Entra), which means the new certificate has to be imported by hand. See below.

Rotating the Signing Certificate​

Rotation is a re-import, not a reconfiguration:

  1. In Entra, under SAML Certificates, create or activate the new certificate as normal.
  2. In Prism, open Admin Portal > Identity Providers > SAML 2.0 and edit the provider.
  3. Re-run the import against the same App Federation Metadata Url used in Step 6, and save.

The imported certificate replaces the stored one, and the thumbprint shown in Prism should match the newly active certificate in Entra.

tip

To roll over with no window of failed logins, put both certificates in the Signing Certificate field, comma-separated, while Entra is still switching over. Prism accepts an assertion signed by either one. Remove the retired certificate once the new one is active everywhere.

  • Identity Providers, All provider types and the full SAML field reference
  • SSO Configuration, Troubleshooting SAML sign-in failures and Entra error codes
  • Users, Create the Prism accounts that federated logins are matched to