Skip to main content
This is an Enterprise feature on Novu Cloud. Configure it as the organization Owner from Settings > Organization > Security after we enable self-serve, or email [email protected] and we will do the Novu side with you. Domain verification and activation are covered in SAML SSO & SCIM.
Use this when the identity provider supports OpenID Connect and you want the authorization code flow rather than SAML. Okta Workforce, Microsoft Entra ID, and Google Workspace each have a SAML guide. Use those when you want the named SAML setup. Use this page when the provider is something else, or when you specifically need OIDC. The Security tab splits the work into three parts: redirect URI, endpoints, and client credentials. If we are configuring the connection, send us the same values the tab asks for.

​
Before you start

  • An Enterprise organization on Novu Cloud.
  • One or more email domains verified on the Security tab. After activation, an email on a verified domain has to sign in through this provider.
  • Permission in the IdP to create a confidential client that uses the authorization code grant, and to set a redirect URI.
  • The authorized redirect URI shown on the Security tab when OIDC Provider is selected, or the redirect URI we send you.
Switching an existing connection from SAML to OIDC, or the other way, removes the current connection and starts again. The Security tab warns you before it does that.

​
Register the application

1

Create a confidential client

In the IdP, create an application that uses the authorization code grant. Public clients and implicit flow are not this setup. The application has to be allowed to release the scopes openid, email, and profile, so the ID token can carry the claims below.Copy the authorized redirect URI from the Security tab and add it to the IdP’s allowed redirect URLs. It has to match exactly, including the scheme and any trailing path. A redirect URI the IdP does not list is rejected before Novu ever sees an ID token.
2

Provide the endpoints

Paste the IdP’s discovery endpoint. On most providers this is the issuer URL ending in /.well-known/openid-configuration. Novu reads the authorization, token, and user info URLs from that document.If the IdP does not publish a discovery document, choose manual configuration and provide:
3

Provide the client credentials

Paste the client ID and client secret from the IdP application. The secret is a credential. Send it to us in the same channel you already use with Novu support, or paste it on the Security tab. Do not put it in a ticket that other people can read later if you can avoid it.If the IdP only shows the secret once, store it before you close that screen. A new secret means updating the connection. On a live connection, that update applies immediately.

​
Claims the ID token should include

The setup screen lists sub and email as the identity claims it reads. Enterprise OIDC also expects an email_verified claim. Some providers, including Microsoft Entra, omit email_verified or send it in a non-standard way. If the test fails for that reason, contact us. We can mark email as verified for that IdP. Do that only when you trust the IdP. Treating an unverified email as verified, from an IdP you do not control, is an account-takeover risk.

​
Test it, then turn it on

Run a test sign-in with a user whose email is on a verified domain and who is allowed to use the OIDC application. For a new connection, the test does not change sign-in for anyone else. Activate after it succeeds.
After activation, anyone signing in with an email on a verified domain must use this IdP. Editing a live connection, including a new client secret or a changed token URL, applies immediately.

​
What your users experience

  • They enter their work email on the Novu sign-in page. Novu redirects them to the authorization URL. After they sign in, the IdP redirects back to the authorized redirect URI with an authorization code. Novu exchanges that code at the token URL.
  • IdP-initiated login from an app tile is a SAML feature. It is not available for this OIDC connection.
  • If the person has multi-factor authentication on their Novu account, they still complete it after the IdP returns.
  • Removing the connection does not delete Novu accounts. Those people need another sign-in method that is still available on the account.
  • There is no OIDC-specific directory protocol. If the IdP can also push SCIM 2.0, use custom SCIM directory sync on this same connection. Until then, the person is created in Novu when they first sign in.

​
If the test fails

Compare the URI registered in the IdP with the authorized redirect URI on the Security tab, character for character.
Open the discovery URL in a browser. It should return JSON that includes authorization_endpoint and token_endpoint. If the IdP has no such document, switch to manual configuration and paste those two URLs.
The client is not allowed to request email, or the IdP only puts email on the user info endpoint. Allow the email scope. If the claim is only on user info, set the user info URL in manual configuration.
Contact us before you remap other claims. Some providers do not send this claim. We can trust the IdP for email verification when you are confident the IdP only issues tokens for accounts it has verified.
Email [email protected] or your Slack Connect channel if you want us to enter the client secret and endpoints for you. Tell us the organization name and the email domain.