Skip to main content
This guide turns on SCIM provisioning for the Modem app integration in Okta. Read Directory Sync first if you haven’t — it covers the token, roles, and the limits that apply whatever directory you use. 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 already configured, using the same Okta app integration — see Okta SAML
  • Directory Sync enabled for your Modem organization, and the owner role in it
  • Administrator access to your Okta org, with permission to configure provisioning
Set up single sign-on first, and finish it. Provisioning creates Modem accounts but no way to sign in, and the two have to agree on one identifier — see Matching the SSO identity below.

​
Setup

1

Generate a token in Modem

In the Modem dashboard, go to Settings → Directory Sync and click Generate token. Copy it — it is shown once. Copy the SCIM base URL from the same page:
2

Turn on SCIM provisioning for the app

In the Okta Admin Console, open your Modem app integration, go to the General tab, edit App Settings, and set the provisioning mode to SCIM. Save. A Provisioning tab appears.
3

Configure the SCIM connection

On the Provisioning tab, under Integration, click Edit and set:Leave Import New Users and Profile Updates and Import Groups off. Modem is the destination, not a source of truth about your people.
4

Test the credentials

Click Test Connector Configuration (called Test API Credentials in some Okta versions). Okta reads the endpoint’s capabilities and lists what it found. Save once it passes; see Troubleshooting if it does not.
5

Enable the provisioning actions

Still on the Provisioning tab, choose To App in the left column and click Edit. Enable:
  • Create Users
  • Update User Attributes
  • Deactivate Users
Save. Deactivate Users is the one that matters most: without it, unassigning someone in Okta leaves their Modem access in place.
6

Assign people

On the app’s Assignments tab, assign the people or groups who should have Modem. Each assignment provisions an account. Assign one person first and confirm they appear under Provisioned people on Modem’s Directory Sync page before you assign everyone.
7

Push the groups that should grant roles

On the app’s Push Groups tab, add the Okta groups you want to use for Modem roles — typically one group for admins. Okta creates each group in Modem and keeps its membership in step.Only push the groups you intend to map. Every pushed group appears in Modem’s mapping list, and a long list of groups that grant nothing is just noise.
8

Map the groups to Modem roles

Back on Modem’s Settings → Directory Sync page, map each pushed group to Admin or Member and save. Modem re-applies the mapping to everyone already provisioned.

​
Matching the SSO identity

Modem links a provisioned directory record to the person signing in by comparing the SCIM externalId with the SAML NameID. Okta populates externalId with its own immutable user id, so the SAML app has to assert that same id:
  • In the app’s SAML Settings, Application username must be Custom with the expression user.id. This is what the Okta SAML guide sets, and it is the setting that decides the NameID value.
  • Do not use user.email or user.login for either side. Email addresses change.

​
Confirming they match

The check is a single round trip, and it is worth doing before you roll out:
1

Provision one person

Assign the app to a test user and wait for them to appear under Provisioned people on Modem’s Directory Sync page.
2

Have them sign in

Send them to https://app.modem.dev to sign in with Continue with SSO.
3

Check the count

Look at Settings → Team. If the identifiers match, they are the person the directory provisioned, in the role their groups grant. If they do not match, you will see two entries for the same human — one provisioned, one created at sign-in. Fix the Application username setting and remove the extra account.

​
Attribute mapping

Modem reads a small, standard set. The defaults in Okta’s SCIM 2.0 template are already correct; nothing has to be added. Everything else Okta sends — phone numbers, addresses, the Enterprise User extension, roles, entitlements — is accepted and stored, and is not used to decide anyone’s access.

​
Testing the whole cycle

1

Assign

Assign the app to a test user. They appear under Provisioned people in Modem, and in Settings → Team as a member.
2

Promote

Add them to the Okta group you mapped to Admin. Their role in Modem changes to admin.
3

Sign in

Have them sign in with Continue with SSO, and confirm no second account appears.
4

Unassign

Unassign the app in Okta. Their access is revoked and their Modem membership is removed. Any session they had open stops working within five minutes.
5

Reassign

Assign it again. They come back, with the role their groups still grant.

​
Troubleshooting

The token is wrong, expired, or revoked. Generate a fresh one in Modem and paste it again. Okta adds the Bearer prefix itself, so paste only the token value.
Check the base URL: https://app.modem.dev/api/auth/scim/v2, with no trailing slash. Okta appends /Users and /Groups itself.
externalId and the NameID disagree. Set the app’s Application username to the custom expression user.id and confirm as described in Confirming they match.
Modem accepts up to 1,000 direct members in a group, and users only. Split a larger group, and flatten any group that contains other groups — Okta pushes nested members as groups, which Modem rejects.
Deactivate Users is not enabled under Provisioning → To App. Turn it on; Okta then sends the deactivation for subsequent changes.
The list shows groups Okta has actually pushed. Check the Push Groups tab, and that the push has finished — Okta creates the group on its own schedule after you add it.
Tokens expire one year after they are generated. Rotate on Modem’s Directory Sync page, paste the new value into Okta, re-run the test, then revoke the old one.

Directory Sync

The token, roles, lifecycle, and limits.

Okta SAML

The single sign-on half, which has to be set up first.