Enterprise SSO
Let your team sign in to Modem through your company identity provider with SAML 2.0 or OIDC
Enterprise SSO lets the members of your organization sign in to Modem through your company identity provider instead of GitHub or Google. Modem supports SAML 2.0 and OIDC, and has step-by-step guides for Okta, Microsoft Entra ID, and Google Workspace.
To also create and remove Modem accounts automatically from the same directory, see Directory Sync.
Requirements
- The Enterprise plan, with SSO enabled for your organization by Modem
- The owner role in the Modem organization. Admins and members can open the Single Sign-On page but cannot view or change the configuration
- One identity provider per organization: either SAML 2.0 or OIDC, not both
- Access to DNS for the email domain you want to claim, so the domain can be verified
How it works
Copy Modem's values
Go to Settings → Single Sign-On in the Modem dashboard and choose the protocol. The page shows the values your identity provider needs: the SP entity ID and ACS URL for SAML, or the redirect URI for OIDC.
Create the application in your identity provider
Create a SAML app (Okta, Entra) or an OIDC client (Google Workspace) with those values.
Register the provider in Modem
Back on the Single Sign-On page, enter the Email domain you are claiming and, optionally, a Display name for the provider. Then enter the values your identity provider gave you: the IdP entity ID, the sign-on URL, and the signing certificate for SAML, or the issuer URL, client ID, and client secret for OIDC.
Verify your email domain
Publish the DNS record Modem shows you and click verify. See Domain verification below. Sign-in is refused until this succeeds.
Test the sign-in
Sign out, go to https://app.modem.dev, and click Continue with SSO. See Signing in below.
The values you exchange
Modem generates the values in this table from your organization’s numeric id. Copy them from the SSO settings page rather than building them by hand — the page shows the exact strings for your organization.
| Value | Shape |
|---|---|
| Provider id | org-<id> |
| SAML SP entity ID (also called Identifier or Audience URI) | https://app.modem.dev/api/auth/sso/saml2/sp/org-<id> |
| SAML ACS URL (also called Assertion Consumer Service, Reply URL, or Single sign-on URL) | https://app.modem.dev/api/auth/sso/saml2/sp/acs/org-<id> |
| SAML SP metadata URL | https://app.modem.dev/api/auth/sso/saml2/sp/metadata?providerId=org-<id> |
| OIDC redirect URI (callback URL) | https://app.modem.dev/api/auth/sso/callback/org-<id> |
| Domain-verification DNS TXT host | _modem-verification-org-<id>.<domain> |
In each of these, <id> is your Modem organization’s numeric id and org- is literal.
Going the other way, Modem needs these from your identity provider:
| Flow | What Modem needs |
|---|---|
| SAML 2.0 | The IdP Entity ID / Issuer, the Single Sign-On URL, and the X.509 signing certificate. The IdP metadata XML can replace the certificate, but you always enter the entity ID and sign-on URL yourself |
| OIDC | The Issuer URL, the Client ID, and the Client secret |
Domain verification
Before anyone can sign in, your organization has to prove it controls the email domain it is claiming, for example acme.com.
Get the token
Modem issues a verification token on the SSO settings page. The token is stable — requesting it again returns the same value rather than rotating it — and it expires after 7 days if it is never used.
Publish a DNS TXT record
Create a TXT record at _modem-verification-org-<id>.<domain>, where <domain> is the domain you are claiming. The value is the
bare token, with no prefix and no quoting beyond whatever your DNS provider adds itself.
Verify in Modem
Click verify on the SSO settings page. DNS propagation can take anywhere from a few minutes to a few hours, so if verification fails the first time, wait and retry — there is no penalty for retrying.
Signing in
Users go to https://app.modem.dev and click Continue with SSO, then type either their work email address or your Modem organization slug. Modem resolves the provider from the email domain (or from the slug) and sends them to your identity provider. When they come back, they are signed in.
What happens on the Modem side depends on the person:
| Who is signing in | What happens |
|---|---|
| Someone with no Modem account | An account is created for them and they join your organization as a member |
| Someone with a pending Modem invitation | The invitation’s role is honoured instead — an admin invitation makes them an admin — and the invitation is marked accepted |
| An existing Modem user | They keep the same account. SSO is matched to it on the email address your identity provider asserts |
A first-time user joins as a member, or with the role on their pending invitation, including owner. Otherwise, promote someone from Settings → Members; see Team Management for what each role can do.
Requiring SSO
Once your domain is verified, an owner can turn on Require SSO for <domain> in Settings → Single Sign-On. After that, members and admins whose email address is on that domain can only get in through your identity provider — GitHub and Google sign-in are refused with “Your organization requires single sign-on”. Owners are exempt, so a broken identity provider can never lock you out of the page that turns the requirement back off.
Turning it on signs out everyone it applies to, because Modem cannot tell which of their existing sessions came from your provider. A browser that is already open can take up to five minutes to notice. Turning it off takes effect immediately and signs nobody out.
Until you turn it on, SSO is an additional way in rather than a required one, and the other sign-in buttons keep working for the same users.
Identity attributes
Modem stores one stable identifier per user, taken from your identity provider. Choosing the right one matters more than it looks, because Directory Sync matches directory users to Modem users by externalId — and externalId has to be the same value as the SSO identifier.
| Provider | Flow | Identifier to send | The matching SCIM externalId |
|---|---|---|---|
| Okta | SAML | NameID = user.id, the Okta user id |
Okta sends the Okta user id as externalId by default |
| Microsoft Entra ID | SAML | Unique User Identifier (Name ID) = user.objectid |
Entra’s default is mailNickname — change it to objectId |
| Google Workspace | OIDC | The sub claim, Google’s stable global user id |
Nothing to configure — sub is what Modem stores |
For SAML, Modem reads the rest of the profile from the assertion like this:
| What Modem wants | Where it reads it |
|---|---|
| Account identity | The assertion’s NameID |
An attribute named exactly email; if it is absent, Modem falls back to the NameID |
|
| Name | The attributes givenName and surname; failing that displayName; failing that the NameID |
So every SAML app should send a NameID set to the stable immutable id, plus an attribute statement carrying email, givenName, and surname.
Limitations
- SP-initiated sign-in only. Users must start from the Modem sign-in page. IdP-initiated sign-in — the Okta dashboard tile, the Entra “My Apps” tile — is not supported and is rejected.
- Assertions must be signed. Modem rejects unsigned SAML assertions. Signing the whole response as well is fine but not required.
- Encrypted assertions are not supported.
- Assertions are single-use. Each one may be consumed once, and must be consumed within a few minutes of being issued.
- One provider per organization, either SAML 2.0 or OIDC.
- Owners are always exempt from the SSO requirement, and the requirement only covers members whose email address is on the verified domain — see Requiring SSO.
- No single logout (SLO). Signing out of Modem does not sign the user out of your identity provider, or the reverse.
Troubleshooting
No single sign-on provider for that address
The email domain typed at Continue with SSO has no provider registered against it. Check that the domain on the SSO settings page matches the domain in the address, and that the person is using their work address rather than a personal one.
Single sign-on is not finished being set up
The provider exists but the domain has not been verified. Publish the DNS TXT record and verify, as described in Domain verification.
Start single sign-on from Modem
Someone launched Modem from a tile in your identity provider’s dashboard. Modem only accepts SP-initiated sign-in, so send them to
https://app.modem.dev and have them click Continue with SSO instead.
The assertion is rejected
Check that your identity provider is signing the assertion, that the certificate registered in Modem is the current one, and that the Audience URI in the app matches the SP Entity ID Modem shows. A certificate rolled in the IdP has to be re-entered in Modem.
Signed in, but with the wrong role
Roles come from Modem, not from your identity provider. A first-time user joins as a member unless they had a pending invitation carrying a different role. Change roles in Settings → Members.