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

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/v2

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.

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

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

Send them to 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
Email 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

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

Sign in

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

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

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

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.

Was this page helpful?