> ## Documentation Index
> Fetch the complete documentation index at: https://modem.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/enterprise/scim) 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](/docs/enterprise/sso) already configured, using the **same Okta app integration** — see [Okta SAML](/docs/enterprise/sso-okta)
* Directory Sync enabled for your Modem organization, and the **owner** role in it
* Administrator access to your Okta org, with permission to configure provisioning

<Warning>
  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](#matching-the-sso-identity) below.
</Warning>

## Setup

<Steps>
  <Step title="Generate a token in Modem">
    In the [Modem dashboard](https://app.modem.dev), go to **Settings** → **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
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](#troubleshooting) if it does not.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/docs/enterprise/sso-okta#sending-the-okta-user-id) 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Have them sign in">Send them to `https://app.modem.dev` to sign in with **Continue with SSO**.</Step>

  <Step title="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.
  </Step>
</Steps>

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

<Steps>
  <Step title="Assign">
    Assign the app to a test user. They appear under **Provisioned people** in Modem, and in **Settings** → **Team** as a member.
  </Step>

  <Step title="Promote">Add them to the Okta group you mapped to **Admin**. Their role in Modem changes to admin.</Step>
  <Step title="Sign in">Have them sign in with **Continue with SSO**, and confirm no second account appears.</Step>

  <Step title="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.
  </Step>

  <Step title="Reassign">Assign it again. They come back, with the role their groups still grant.</Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="A user provisions, then 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](#confirming-they-match).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Provisioning stops working after about a year">
    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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Directory Sync" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/shield.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=ee1ca3093fcbdf45ec5dc1a74652bed6" href="/docs/enterprise/scim" width="24" height="24" data-path="icons/shield.svg">
    The token, roles, lifecycle, and limits.
  </Card>

  <Card title="Okta SAML" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/shield.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=ee1ca3093fcbdf45ec5dc1a74652bed6" href="/docs/enterprise/sso-okta" width="24" height="24" data-path="icons/shield.svg">
    The single sign-on half, which has to be set up first.
  </Card>
</CardGroup>