Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

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
Email 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:

  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.

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.

Last updated on

Was this page helpful?