Skip to main content
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

Setup runs in two passes, because Okta needs an Audience URI that Modem only issues once the provider exists.
1

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.
2

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) — a placeholder for now, for example https://app.modem.dev. You replace this in step 6 with the SP Entity ID Modem generates.
  • Name ID format — Unspecified or Persistent. 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.
3

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.
4

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.
5

Register Okta in Modem

In the Modem dashboard, go to Settings → SSO, choose SAML 2.0, and enter the sign-on URL, issuer, and certificate (or the metadata XML) you just copied, along with the email domain you are claiming.
6

Paste Modem's SP Entity ID back into Okta

The SSO settings page now shows Modem’s SP Entity ID (Audience URI). Copy it exactly, return to the Okta app’s General tab → SAML Settings → Edit, and replace the placeholder Audience URI (SP Entity ID) with it. Save.
The SP Entity ID will look like your Okta org’s own issuer URL. That is expected — copy it exactly as Modem shows it rather than adjusting it to look more like a Modem URL.
7

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.
8

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:
Do not use user.email or user.login.
The NameID is the key Modem hangs the account off, and it must be a stable, immutable id. Directory Sync matches directory users to Modem users by externalId, which has to be the same value — the Okta user id. Okta’s SCIM integration sends the Okta user id as externalId by default, so user.id here pairs cleanly with it. See Okta provisioning.Email addresses change. Matching on email is how an account ends up handed to the wrong person.

​
Attribute mapping

​
Testing the sign-in

Sign out of Modem, or use a private window, then:
  1. Go to https://app.modem.dev
  2. Click Continue with SSO
  3. Enter your work email address, or your Modem organization slug
  4. 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.
Do not test by clicking the Modem tile on your Okta dashboard. Modem accepts SP-initiated sign-in only, so an IdP-initiated launch is rejected with “Start single sign-on from Modem”. This is the single most common support question — it is worth telling your team up front to start from the Modem sign-in page.

​
Troubleshooting

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.
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.
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.
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.
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.
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.

Enterprise SSO

Requirements, domain verification, and sign-in behaviour.

Team Management

Roles, invitations, and auto-join.