Microsoft Entra ID SAML
Connect Modem to Microsoft Entra ID with a SAML enterprise application
This guide sets up Enterprise SSO with Microsoft Entra ID (formerly Azure AD) using a SAML enterprise application. Read the overview first if you haven’t — it covers domain verification, roles, and the limitations that apply to every provider.
The Entra admin center changes regularly, so treat the menu paths and field labels below as a guide; the exact labels move between releases.
Why SAML and not OIDC
Entra also speaks OIDC, but Modem recommends SAML here for one specific reason: Entra’s OIDC sub claim is pairwise. It is a different value for every application registration, so it cannot be correlated with anything the directory sends — including a future SCIM externalId. The object id carried in a SAML assertion is stable and tenant-wide, which is what Modem needs.
Prerequisites
- Enterprise SSO enabled for your Modem organization, and the owner role in it
- Permission to create and configure enterprise applications in your Entra tenant
- Access to DNS for the email domain you are claiming
Setup
Copy Modem's SAML values
In the Modem dashboard, go to Settings → Single Sign-On and choose SAML 2.0. Keep the page open: it shows the SP entity ID and ACS URL Entra needs.
Create the enterprise application
In the Microsoft Entra admin center, go to Enterprise applications → New application → Create your own application,
choose Integrate any other application you don’t find in the gallery, name it something like Modem, and create it.
Open single sign-on and choose SAML
In the new application, go to Single sign-on and choose SAML.
Fill in the Basic SAML Configuration
Edit Basic SAML Configuration and set:
| Field | Value |
|---|---|
| Identifier (Entity ID) | The SP entity ID from Modem, https://app.modem.dev/api/auth/sso/saml2/sp/org-<id> |
| Reply URL (Assertion Consumer Service URL) | The ACS URL from Modem, https://app.modem.dev/api/auth/sso/saml2/sp/acs/org-<id> |
| Sign on URL | https://app.modem.dev/auth/login |
Set the Unique User Identifier and claims
Edit Attributes & Claims.
Set the Unique User Identifier (Name ID) to the source attribute user.objectid, with the format Persistent (or
Unspecified). See Sending the Entra object id below.
Then add three claims with these exact names:
| Claim name | Source attribute |
|---|---|
email |
user.mail |
givenName |
user.givenname |
surname |
user.surname |
Download the signing certificate
Under SAML Signing Certificate, download Certificate (Base64). Alternatively, open the App Federation Metadata Url and copy the XML document it serves — Modem accepts either the certificate or the metadata XML itself. Paste the XML, not the URL: Modem does not fetch it for you.
Register Entra in Modem
From the Set up panel at the bottom of the single sign-on page, copy the Login URL (the sign-on URL) and the Microsoft Entra Identifier (the issuer / entity id).
Back on Modem’s Single Sign-On page, enter the login URL as the Sign-on URL, the Entra identifier as the IdP entity ID, and the certificate (or the federation metadata XML), along with the email domain you are claiming.
Assign users and groups
Under Users and groups, assign the people or groups who should have access to Modem. Anyone not assigned cannot sign in.
Verify your email domain
Publish the DNS TXT record Modem shows on the SSO settings page and click verify. Sign-in is refused until this succeeds — see Domain verification.
Sending the Entra object id
The Unique User Identifier (Name ID) must be user.objectid — the directory object id — and not the user’s mail or UPN.
Attribute mapping
| What Modem wants | Entra value | Notes |
|---|---|---|
| Account identity | Unique User Identifier (Name ID) = user.objectid |
Format Persistent or Unspecified |
Claim email = user.mail |
Short name, empty namespace. Modem falls back to the NameID if this is missing | |
| First name | Claim givenName = user.givenname |
Short name, empty namespace |
| Last name | Claim surname = user.surname |
Short name, empty namespace |
Testing the sign-in
Sign out of Modem, or use a private window, then:
- Go to
https://app.modem.dev - Click Continue with SSO
- Enter your work email address, or your Modem organization slug
- Complete the Microsoft prompt
You should land back in Modem signed in. A user who has never used Modem before gets an account and joins as a member, unless they had a pending invitation carrying a different role.
Troubleshooting
Start single sign-on from Modem
The sign-in started from the Entra My Apps tile rather than from Modem. Go to https://app.modem.dev and click Continue with
SSO. Setting the app’s Sign on URL to https://app.modem.dev/auth/login makes the tile send people to the right place.
Single sign-on is not finished being set up
The domain has not been verified yet. Publish the DNS TXT record from the SSO settings page and click verify. DNS can take minutes to hours to propagate; retrying is safe.
Entra reports an identifier or reply URL mismatch
The Identifier (Entity ID) in Entra does not match the SP Entity ID Modem shows, or the Reply URL is not the ACS URL from Modem. Copy both again from the SSO settings page, character for character.
Users sign in but have no name or email
The claims are almost certainly still using Entra’s default URI names. Edit each claim so its Name is the short email,
givenName, or surname and its Namespace is empty.
The signing certificate expired
Entra SAML signing certificates have an expiry, and can be rolled early. After a roll, download the new Certificate (Base64) and update it on the Modem SSO settings page, otherwise assertions stop validating.
A user is not assigned
Entra refuses the sign-in before it ever reaches Modem if the person is not assigned to the application. Check Users and groups.