Okta provisioning
Provision Modem users and groups automatically from Okta with SCIM 2.0
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
Setup
Generate a token in Modem
In the Modem dashboard, go to Settings → Single Sign-On → Directory sync and click Generate token. Copy it — it is shown once. Copy the SCIM base URL from the same page:
https://app.modem.dev/api/auth/scim/v2Turn 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.
Configure the SCIM connection
On the Provisioning tab, under Integration, click Edit and set:
| Setting | Value |
|---|---|
| SCIM connector base URL | https://app.modem.dev/api/auth/scim/v2 |
| Unique identifier field for users | userName |
| Supported provisioning actions | Push New Users, Push Profile Updates, and Push Groups |
| Authentication Mode | HTTP Header |
| Authorization / Bearer token | the token you generated in Modem |
Leave Import New Users and Profile Updates and Import Groups off. Modem is the destination, not a source of truth about your people.
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.
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.
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.
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.
Map the groups to Modem roles
Back on Modem’s Settings → Single Sign-On → Directory sync tab, 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.emailoruser.loginfor either side. Email addresses change.
Confirming they match
The check is a single round trip, and it is worth doing before you roll out:
Provision one person
Assign the app to a test user and wait for them to appear under Provisioned people on Modem’s Directory sync tab.
Have them sign in
https://app.modem.dev to sign in with Continue with SSO.Check the count
Look at Settings → Members. If the identifiers match, they are the person the directory provisioned, in the role their groups grant. If they do not match, sign-in fails or creates a second account. Fix the Application username setting, and remove any 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.
| What Modem uses | Okta attribute | Notes |
|---|---|---|
| Account link | externalId |
Okta’s immutable user id. Must equal the SAML NameID |
| Sign-in address | userName |
Also the unique identifier field configured above |
emails (work) |
Falls back to userName when absent |
|
| Name | givenName, familyName, displayName |
Used for display only |
| Active state | active |
Set by assigning and unassigning; do not map it to something else |
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
Assign
Assign the app to a test user. They appear under Provisioned people in Modem, and in Settings → Members as a member.
Promote
Sign in
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.
Reassign
Troubleshooting
Test Connector Configuration fails with 401
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.
Test Connector Configuration fails with 404 or cannot reach the endpoint
Check the base URL: https://app.modem.dev/api/auth/scim/v2, with no trailing slash. Okta appends /Users and /Groups itself.
A provisioned user cannot sign in, or signing in creates a second account
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.
Push Groups fails on a large group
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.
Unassigning someone leaves their Modem access in place
Deactivate Users is not enabled under Provisioning → To App. Turn it on; Okta then sends the deactivation for subsequent changes.
A pushed group is not in Modem's mapping list
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.
Provisioning stops working after about a year
Tokens expire one year after they are generated. Rotate on Modem’s Directory sync tab, paste the new value into Okta, re-run the test, then revoke the old one.