Okta SAML
Connect Modem to Okta with a SAML 2.0 app integration
This guide sets up Enterprise SSO with Okta using a SAML 2.0 app integration. Read the overview first if you haven’t — it covers domain verification, roles, and the limitations that apply to every provider.
Okta’s admin console is redesigned regularly, so treat the menu paths and field labels below as a guide; the exact labels move between Okta releases.
Prerequisites
- Enterprise SSO enabled for your Modem organization, and the owner role in it
- Administrator access to your Okta org, with permission to create app integrations
- 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 Okta needs.
Create the SAML app integration in Okta
In the Okta Admin Console, go to Applications → Applications → Create App Integration, choose SAML 2.0, and give
the app a name such as Modem.
Fill in the Configure SAML step
On the Configure SAML step:
- Single sign-on URL — the ACS URL from Modem,
https://app.modem.dev/api/auth/sso/saml2/sp/acs/org-<id>. Leave Use this for Recipient URL and Destination URL checked. - Audience URI (SP Entity ID) — the SP entity ID from Modem,
https://app.modem.dev/api/auth/sso/saml2/sp/org-<id>. - Name ID format —
UnspecifiedorPersistent. Either works. - Application username — see Sending the Okta user id below. This is the setting that decides the NameID value, and it is the one thing worth getting right the first time.
Leave Response and Assertion Signature at their defaults. Okta signs the assertion out of the box, which is what Modem requires; Modem rejects unsigned assertions, and signing the response as well is fine but not required.
Add the attribute statements
Still on Configure SAML, under Attribute Statements, add three attributes. The names have to match exactly — Modem looks them up by name.
| Name | Value |
|---|---|
email |
user.email |
givenName |
user.firstName |
surname |
user.lastName |
Copy Okta's SAML details
Finish the wizard, then open the app’s Sign On tab and click View SAML setup instructions (in some Okta versions this is a More details panel). Copy:
- Identity Provider Single Sign-On URL
- Identity Provider Issuer
- The X.509 Certificate
Alternatively, open the Identity Provider metadata link and copy the XML document it serves. Modem accepts either the certificate or the metadata XML itself — paste the XML, not the link, since Modem does not fetch it for you.
Register Okta in Modem
Back on Modem’s Single Sign-On page, enter the sign-on URL, the issuer as the IdP entity ID, and the certificate (or the metadata XML) you just copied, along with the email domain you are claiming.
Assign the app to your users
On the app’s Assignments tab, assign it to 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 Okta user id
In Okta, the NameID value comes from the app’s Application username setting, not from the Name ID format. To send the Okta user id, set Application username to Custom and use the expression:
user.id
Do not use user.email or user.login.
Attribute mapping
| What Modem wants | Okta value | Notes |
|---|---|---|
| Account identity | NameID, from Application username = user.id |
The immutable Okta user id |
Attribute email = user.email |
Modem falls back to the NameID if this is missing | |
| First name | Attribute givenName = user.firstName |
|
| Last name | Attribute surname = user.lastName |
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 Okta 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 Okta dashboard tile rather than from Modem. Go to https://app.modem.dev and click Continue with
SSO. If it helps, edit the app’s tile in Okta to link to https://app.modem.dev so the tile sends 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.
Okta reports an audience or destination mismatch
The Audience URI (SP Entity ID) in Okta does not match the SP Entity ID Modem shows, or the Single sign-on URL is not the ACS URL from Modem. Copy both again from the SSO settings page, character for character.
Users sign in but their names or emails are wrong
Check the attribute statements. The names have to be exactly email, givenName, and surname — Okta will happily save a
misspelled name, and Modem then falls back to the NameID.
The certificate expired or was rotated
Okta signing certificates have an expiry. When you roll one in Okta, copy the new X.509 Certificate from View SAML setup instructions and update it on the Modem SSO settings page, otherwise assertions stop validating.
A user is not assigned
Okta refuses the sign-in before it ever reaches Modem if the person is not assigned to the app. Check the app’s Assignments tab.