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

# Okta directory sync

> Push Okta Workforce users to Novu with SCIM 2.0, using the same SAML app, a SCIM base URL, and a bearer token.

<Note>
  Directory sync is an Enterprise feature on [Novu Cloud](https://dashboard.novu.co). It sits under SSO on **Settings** > **Organization** > **Security**, which the organization **Owner** sees after we enable self-serve. Shared behavior, including offboarding and the bearer token, is on [Directory sync](/platform/account/directory-sync). The SAML app comes from [Okta Workforce SSO](/platform/account/sso/okta).
</Note>

Use the same Okta application you created for SAML. Okta pushes create, update, and deactivate events to a SCIM 2.0 endpoint. Novu does not poll Okta.

## Before you start

* The [Okta Workforce SSO](/platform/account/sso/okta) connection exists. It does not have to be activated yet. Until it is activated, Okta can provision people and they cannot sign in.
* The email domain is verified on that connection. Users outside that domain are ignored.
* An Okta admin who can edit the SAML app's **General** settings. The **Provisioning** tab is not on that app until SCIM is enabled.
* The **SCIM endpoint URL** and **bearer token** from the Security tab. Select **Start configuration**. The provider is Okta because the SSO connection is Okta. You do not choose it again.

<Warning>
  The bearer token is shown once, in the session that generates it. Paste it into Okta before you leave the page. If you lose it, select **Generate new token**. The previous token keeps working for 10 minutes. After that, Okta's **Test API Credentials** fails until you save the new token.
</Warning>

There is no separate activate button. After you save the URL and token in Okta and turn on the **To App** operations, Okta can start pushing.

## Configure provisioning in Okta

<Steps>
  <Step title="Enable SCIM on the SAML app">
    The app from [Okta Workforce SSO](/platform/account/sso/okta) is a custom SAML integration. Okta hides **Provisioning** on that app until SCIM is turned on.

    Open the app's **General** tab. In **App Settings**, select **Edit**. In **Provisioning**, select **SCIM**, then **Save**. The **Provisioning** tab appears after the save.

    If **Provisioning** is not in **App Settings**, SCIM is not enabled for this Okta org. Okta support has to turn that feature on before this app can push users.
  </Step>

  <Step title="Enter the SCIM credentials">
    Open the **Provisioning** tab. Under **Settings** > **Integration**, select **Edit**.

    | Okta field | Value |
    | - | - |
    | SCIM connector base URL | SCIM endpoint URL from Novu |
    | Unique identifier field for users | `userName` |
    | Supported provisioning actions | **Push New Users** and **Push Profile Updates**. Add **Push Groups** only if you need groups stored. Leave **Import New Users and Profile Updates** off. That option imports people into Okta. |
    | Authentication Mode | **HTTP Header** |
    | Authorization | Bearer token from Novu |

    Save. If Okta offers a credential test on this screen, run it before you save. A failure here is the base URL or the token, including a token copied with extra spaces or replaced after the 10-minute overlap.
  </Step>

  <Step title="Choose what Okta pushes">
    Under **To App**, enable:

    * **Create Users**
    * **Update User Attributes**
    * **Deactivate Users**

    Select **Save**. Leave **Deactivate Users** on if you want a person who is unassigned or deactivated in Okta to lose their Novu session. Without it, Okta will not tell Novu to deactivate them.
  </Step>

  <Step title="Map the email attribute">
    Under **Attribute Mappings**, confirm `email` (`user.email`) is mapped and is applied on create and update.

    This is separate from `userName`. Novu reads the email from the SCIM `emails` attribute. Okta's `email` mapping is what fills that attribute. If `userName` is the email address and `email` is not mapped, provisioning fails. Novu does not copy `userName` into the email field.
  </Step>

  <Step title="Push groups only if you need them stored">
    Open **Push Groups**, enable it, choose the groups, and save.

    Pushed groups are stored. They do not change Novu roles (Owner, Admin, Author, Viewer). Ask us if you want a group to set a role. If we turn that on later, only direct membership counts.
  </Step>
</Steps>

## What Novu stores

These mappings are fixed on the Security tab:

| SCIM attribute | Novu user field |
| - | - |
| `userName` | Username / primary identifier |
| `emails[0].value` | Email address |
| `name.givenName` | First name |
| `name.familyName` | Last name |
| `active` | Enabled or deactivated |

Other Okta profile fields are not applied from this page.

## Test a user

Assign the app to someone whose email is on a verified domain, with **Create Users** enabled. On the Security tab, the test step lists recent activity with email, name, time, and **Active** or **Deprovisioned**.

Okta's provisioning cycle is often several minutes. A user who never appears is usually on the wrong domain, missing `email`, or not assigned to the app.

**Complete** closes the wizard. It does not turn provisioning on. Provisioning is already on once Okta has the URL, the token, and the **To App** operations.

## When someone leaves

Unassigning or deactivating them in Okta, with **Deactivate Users** enabled, deactivates the Novu account and revokes their sessions after Okta's next provisioning cycle. The Novu account is not deleted.

If they were also invited from **Settings** > **Team**, that invited membership stays. Remove it there if they should lose the organization.

**Deactivate** pauses new sync from this directory and withdraws organization access that only this directory granted. It does not delete Novu accounts, the directory, a SCIM bearer token, or a stored Google service account key. A membership created from **Settings** > **Team**, or still granted by another directory, stays.

**Activate** resumes sync. Access returns from the directory's current state, not from a snapshot of who was a member before the pause.

**Remove** deletes the directory after you type the organization name.

* A membership that came only from this directory is removed.
* An invitation membership, or access still granted by another directory, stays.
* The Novu account is not deleted. If this was the only directory for that person, removing it does not sign them out. Deactivate them in the identity provider, and wait until that change has synced, before you remove the directory if they must lose access.
* For SCIM, the bearer token is deleted. Setting directory sync up again creates a new endpoint and a new token.
* For Google Workspace, Novu's copy of the service account key is destroyed. That does not delete the key in Google Cloud. Delete it there if it may have leaked.

## If Okta provisioning fails

<AccordionGroup>
  <Accordion title="The Integration credential test fails">
    The base URL or the bearer token does not match what the Security tab shows. Generate a new token if the 10-minute window has passed, paste it into **Authorization**, and test again. **Authentication Mode** has to be **HTTP Header**.
  </Accordion>

  <Accordion title="Okta reports a provisioning error for email">
    Map `email` (`user.email`) as well as `userName`. Both have to be sent.
  </Accordion>

  <Accordion title="The user is assigned and still missing in Novu">
    Wait for Okta's cycle, then confirm the email domain is verified on the SSO connection. Users on other domains are dropped.
  </Accordion>

  <Accordion title="They were deactivated in Okta and can still open Novu">
    Confirm **Deactivate Users** is enabled and saved. Then wait for the next cycle. If they still have access, check for a membership created by invitation.
  </Accordion>
</AccordionGroup>

Email [support@novu.co](mailto:support@novu.co) with the Okta provisioning error text if the API test succeeds and users still fail. Include the email address Okta tried to push.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.