Skip to main content
Directory sync is an Enterprise feature on Novu Cloud. 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. The SAML app comes from Okta Workforce SSO.
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 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.
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.
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

1

Enable SCIM on the SAML app

The app from Okta Workforce SSO 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.
2

Enter the SCIM credentials

Open the Provisioning tab. Under Settings > Integration, select Edit.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.
3

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

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

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.

​
What Novu stores

These mappings are fixed on the Security tab: 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

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.
Map email (user.email) as well as userName. Both have to be sent.
Wait for Okta’s cycle, then confirm the email domain is verified on the SSO connection. Users on other domains are dropped.
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.
Email [email protected] with the Okta provisioning error text if the API test succeeds and users still fail. Include the email address Okta tried to push.