Skip to main content
Zenovaydocs
5 min read

OAuth 2.0 / OpenID Connect SSO Setup

This guide covers how to configure OAuth 2.0 or OpenID Connect (OIDC) Single Sign-On with Zenovay. For provider-specific instructions, see the guides for Okta, Microsoft Entra ID, or Auth0.

SSO requires a Scale or Enterprise plan and Owner or Admin permissions.

Choosing Between OAuth 2.0 and OpenID Connect

FeatureOAuth 2.0OpenID Connect
Auto-discoveryNo — you enter all URLs manuallyYes — Zenovay fetches configuration from the issuer URL
ID Token verificationNot applicableAutomatic via JWKS
Best forIdPs without OIDC supportModern IdPs (Okta, Entra ID, Auth0, Keycloak)

If your identity provider supports OpenID Connect, choose OIDC — it provides stronger security with automatic ID token verification and simpler configuration via auto-discovery.

Zenovay Configuration Value

Copy this value into your identity provider's application configuration:

SettingValue
Redirect URI / Callback URLhttps://auth.zenovay.com/api/sso/oauth/callback

OAuth 2.0 Setup

Step 1: Create an OAuth Application in Your IdP

  1. In your identity provider, create a new OAuth 2.0 application
  2. Set the application type to Web Application
  3. Enter the redirect URI: https://auth.zenovay.com/api/sso/oauth/callback
  4. Note the Client ID and Client Secret provided by your IdP

Step 2: Collect IdP Values

You will need the following values from your identity provider:

ValueDescription
Client IDApplication identifier assigned by your IdP
Client SecretApplication secret assigned by your IdP
Authorization URLURL where users are sent to authenticate
Token URLURL where Zenovay exchanges the authorization code for tokens
User Info URLURL where Zenovay retrieves user profile information

Step 3: Add Provider in Zenovay

  1. Sign in to Zenovay as an Owner or Admin
  2. Go to Settings > Authentication > SSO
  3. Click Add SSO Provider
  4. Select OAuth 2.0 as the protocol
  5. Enter a name for the provider
  6. Fill in all five values from Step 2
  7. Click Save

OpenID Connect Setup

Step 1: Create an OIDC Application in Your IdP

  1. In your identity provider, create a new OpenID Connect application
  2. Set the application type to Web Application
  3. Enter the redirect URI: https://auth.zenovay.com/api/sso/oauth/callback
  4. Ensure the following scopes are granted: openid, email, profile
  5. Note the Client ID and Client Secret provided by your IdP

Step 2: Collect IdP Values

You will need the following values:

ValueDescription
Client IDApplication identifier assigned by your IdP
Client SecretApplication secret assigned by your IdP
Issuer URLYour IdP's OIDC issuer URL (used for auto-discovery)

The Issuer URL is used to automatically discover your IdP's authorization, token, user info, and JWKS endpoints via the .well-known/openid-configuration document. You do not need to enter these URLs manually.

Step 3: Add Provider in Zenovay

  1. Sign in to Zenovay as an Owner or Admin
  2. Go to Settings > Authentication > SSO
  3. Click Add SSO Provider
  4. Select OpenID Connect as the protocol
  5. Enter a name for the provider
  6. Fill in the three values: Client ID, Client Secret, and Issuer URL
  7. Click Save

Domain Verification

After adding an OAuth 2.0 or OIDC provider, verify your email domain:

  1. In the SSO provider settings, click Add Domain
  2. Enter your email domain (e.g., company.com)
  3. Follow the domain verification steps
  4. Once verified, users with that email domain will be directed to this SSO provider

Testing the Connection

  1. Open an incognito/private browser window
  2. Go to auth.zenovay.com
  3. Enter an email address from your verified domain
  4. You should be redirected to your identity provider
  5. Sign in with your IdP credentials
  6. You should be redirected back to the Zenovay dashboard

Security Features

Zenovay automatically applies these security measures for OAuth/OIDC connections:

  • PKCE (Proof Key for Code Exchange) — protects the authorization code exchange
  • State parameter — cryptographically signed to prevent CSRF attacks
  • Nonce validation (OIDC) — prevents token replay attacks
  • ID token verification (OIDC) — validates tokens using the IdP's JWKS endpoint

Enforcing SSO

Once testing is successful:

  1. Go to Settings > Authentication > SSO
  2. Toggle Enforce SSO to on
  3. All team members with your verified domain will be required to sign in via SSO

Before enforcing SSO, ensure at least one Owner account can still sign in via email/password as a backup in case of an IdP outage.

Need Help?

Was this page helpful?