Skip to main content
SAML SSO, OpenID Connect (OIDC), and directory sync are available to Enterprise customers on Novu Cloud. Self-hosted Novu signs in with email and password. See pricing and Self-hosted and Novu Cloud.
Use this when your company wants the Novu dashboard to follow the same identity provider (IdP) you already use for other internal tools. People sign in with their work account. When someone leaves, you remove their dashboard access from that directory instead of resetting a password in Novu. This page is about the people who sign in to Novu. It does not create subscribers. Subscribers are the people your workflows notify, and they stay under your control through the API. For Google, GitHub, and email-and-password sign-in, see Authentication. For roles after someone is in the organization, see Roles and permissions.

​
What you can connect

Novu is the service provider. Your IdP checks the person’s credentials, including any MFA the IdP requires, and sends Novu a signed login. Novu then opens the dashboard session. Directory sync is attached to an SSO connection. Set up SAML or OIDC first. You can finish the directory configuration before you activate SSO. People can be provisioned in that window, but they cannot sign in until SSO is active. An SSO domain is not the same thing as a verified domain. A verified domain lets colleagues join the organization. An SSO domain forces sign-in through the IdP. You can use both. Verifying a domain for invitations does not turn on SSO.

​
Choose how to configure it

You need someone who can publish a DNS TXT record for the email domain, and someone who can create an application in the IdP. Those are often two different people. Each provider guide is a separate page, so you can hand the IdP admin the Okta, Entra, or Google Workspace page on its own.

​
We configure it with you

Email [email protected] or message your Slack Connect channel and tell us the email domain and the IdP. We send you the service provider values for that provider (the URLs and IDs in the provider guide). You create the application, then send us the IdP metadata, or the OIDC client credentials if that is the protocol you are using. We test with you and turn the connection on. Use this when you want us to own the Novu side, or when the Security tab described next is not available yet.

​
You configure it from the dashboard

Self-serve setup is off until we enable it for your organization. After that, the organization Owner sees a Security tab on Settings > Organization: https://dashboard.novu.co/settings/organization#/organization-security Other roles do not see that tab. If you are the IdP admin and not the Owner, do the IdP work together with the Owner, or ask the Owner to open the page. If the tab is missing, self-serve is not enabled. Ask us to turn it on, or use the assisted path above. There is nothing to flip in the dashboard until we do. The Security tab walks through domain verification, the IdP, a test sign-in, and activation. Directory sync is on the same tab, under the SSO section.

​
Set up SSO from the dashboard

1

Open Security as the Owner

Go to Settings > Organization > Security, or use the link above.
2

Verify the email domain

Add the domain people will sign in with, such as acme.com. The page shows a DNS TXT record. Publish that record, then come back and confirm the domain is verified. You can add more than one domain. The connection cannot be configured until at least one domain is verified.For SAML, the match is exact. A connection for acme.com accepts [email protected] and does not accept [email protected]. Subdomain matching is not on this page. Ask us if you need it. The domain on the connection has to be a registrable domain, such as acme.com, before subdomain matching can be enabled.
3

Choose the provider

Under SAML, the choices are Okta Workforce, Microsoft Entra (formerly AD), Google Workspace, and Custom SAML Provider. Under OpenID Connect, the choice is OIDC Provider.Switching an existing connection to a different provider removes the current connection and starts the configuration again. The page warns you before it does that.
4

Configure the IdP

Open the guide for your provider. The Security tab shows the values to paste into the IdP, and the place to paste the IdP’s metadata or credentials back.
5

Run a test sign-in

Use a person who is assigned to the application in the IdP and whose email is on a verified domain. For a new connection, this test does not change sign-in for anyone else. The connection is not live until you activate it.
6

Activate the connection

After the test succeeds, activate it. From that moment, anyone signing in with an email on a verified domain must use the IdP.
Editing a connection that is already active applies immediately. A wrong URL, certificate, or attribute mapping can stop everyone on that domain from signing in, including people who already had a Novu account. Change a live connection when someone is available to fix a failed login, and run the test again.

​
How sign-in works

People start from the Novu sign-in page. They enter their work email. Novu sends them to the IdP, the IdP authenticates them, and they return to the dashboard. A few consequences that are easy to miss:
  • For a SAML connection, an existing Novu account with a matching email is linked to the enterprise login. The person keeps that account and signs in through the IdP from then on.
  • If the person also has multi-factor authentication on their Novu account, they still complete that step after the IdP accepts them.
  • Someone who is not assigned to the application in the IdP cannot sign in, even if they know the Novu URL.
  • If the connection is removed, Novu accounts are not deleted. Those people need another sign-in method that is still available on the account, such as a password, Google, or GitHub.
  • Starting login from an app tile inside the IdP (IdP-initiated SAML) is a separate switch. It is not part of the Security tab, and it is not available for OIDC. The sign-in flow above is the one to use. Ask us if you have a specific reason to start from the IdP.

​
Team members who sign in currently with Google or GitHub

Continue with Google and Continue with GitHub on the sign-in page are available to every Novu Cloud account. They are separate from the SSO connection for your organization. Using one of those buttons is not the same as having SSO configured. After you activate the connection, a person whose email is on a verified domain keeps the same Novu account. Sign-in for that email goes through the IdP. They can start in either of these ways:
  • Enter the work email and select Continue. Novu sends them to the IdP. There is no password step for that email.
  • Select Continue with Google or Continue with GitHub and choose the account that uses that work email. Google or GitHub confirms the account, then Novu sends them to the IdP before opening the dashboard.
A person whose email is not on a verified domain can keep using Google, GitHub, or a password. A person the IdP does not assign to the Novu application cannot sign in, including someone who previously used the Google button. Without directory sync, a person is created in Novu when they first sign in through SSO. That is just-in-time provisioning. Directory sync creates and deactivates people from the directory itself, so a leaver loses access without having to open Novu again.

​
Provider guides

The IdP steps are the same whether you use the Security tab or we configure the connection with you. What changes is where the service provider values come from, and where you return the IdP metadata.

Okta Workforce

SAML application, attribute statements, and metadata URL.

Microsoft Entra ID

Non-gallery enterprise app, claims, and federation metadata.

Google Workspace

Custom SAML app in the Admin console.

Custom SAML provider

Any other SAML 2.0 identity provider.

Custom OpenID Connect

Authorization code flow, discovery URL, client ID, and secret.

​
Directory sync

Directory sync provisions and deprovisions the people who can sign in to this organization. It is a separate setup from SSO, on the same Security tab, and it needs an SSO connection first.

How directory sync works

SCIM attributes, bearer tokens, offboarding, and what the Security tab does.

Okta

SCIM connector base URL, API token, and push settings.

Microsoft Entra ID

Tenant URL, secret token, and automatic provisioning.

Google Workspace

Service account, domain-wide delegation, and Admin SDK sync.

Custom SCIM

Any SCIM 2.0 provider behind a custom SAML or OIDC connection.

​
If sign-in or provisioning fails

The connection is not active yet. A successful test does not change sign-in for the domain. Activate it after you are ready for that domain to use the IdP. The same check is on each provider page, next to the steps.
The required attribute is missing or named differently. Okta needs mail. Google Workspace needs the app attribute email. A custom SAML provider needs mail. Entra needs the email claim mapped from user.mail. For SCIM, emails has to be present even when userName is an email address. See Directory sync.
They also have to be assigned to the Novu application. In Google Workspace, the SAML app has to be ON for their organizational unit.
For SAML, sales.acme.com does not use a connection registered for acme.com unless we have enabled subdomain matching. The address also has to be on a domain you verified with the TXT record.
The bearer token was copied incompletely, or a new token was generated and the 10-minute overlap has passed. Generate a new token, put it in the IdP, and save. Details are on Directory sync.
Wait for the next provisioning cycle. Entra and Okta are often several minutes behind. Google is about five minutes, or immediate if you use Sync now. Then check whether they still have a membership that was created by invitation rather than by the directory.
The connection still has the previous signing certificate. Update the certificate on the connection, or send us the new one, before the IdP stops using the old certificate. On a live connection that update applies immediately.

​
Ask us for help

Email [email protected] or your Slack Connect channel. Tell us the organization name, the email domain, and the IdP. If a test sign-in or a SCIM push failed, include the error from the IdP and the email address you tried. That is enough for us to see whether the connection, the claim mapping, or the directory is what rejected it.

Authentication

Google, GitHub, email and password, MFA, and sessions.

Organizations

How organizations, environments, and billing fit together.

Team members

Invitations, verified domains, and removing members by hand.

Roles and permissions

What Owner, Admin, Author, and Viewer can do after sign-in.