OAuth/OIDC SSO Setup

Scale Plan

Configure OAuth 2.0 or OpenID Connect (OIDC) for single sign-on. Modern alternative to SAML for cloud-native identity providers.

SAML vs OAuth/OIDC

Feature	SAML	OAuth/OIDC
Protocol	XML-based	JSON/REST
Token Format	XML assertion	JWT
Best For	Enterprise IdPs	Cloud apps
Mobile Support	Limited	Excellent
Setup Complexity	Higher	Lower
Auto-Discovery	No	Yes (OIDC)

Supported Providers

Provider	Protocol
Microsoft Entra ID (Azure AD)	OIDC
Okta	OIDC
Auth0	OIDC
Keycloak	OIDC
Custom	OAuth 2.0 / OIDC

Zenovay OAuth/OIDC Configuration

Redirect URI

Your identity provider will need this redirect URI:

Setting	Value
Redirect URI / Callback URL	https://auth.zenovay.com/api/sso/oauth/callback

Required Scopes

Zenovay requires these scopes:

openid
email
profile

Choosing Between OAuth 2.0 and OpenID Connect

Feature	OAuth 2.0	OpenID Connect
Configuration	Enter all endpoint URLs manually	Auto-discovery via Issuer URL
ID Token verification	Not applicable	Automatic via JWKS
Fields needed	Client ID, Client Secret, Auth URL, Token URL, UserInfo URL	Client ID, Client Secret, Issuer URL
Best for	IdPs without OIDC support	Modern IdPs (Okta, Entra ID, Auth0, Keycloak)

Microsoft Entra ID OIDC Setup

Step 1: Register Application

1. Sign in to the Microsoft Entra admin center
2. Go to Identity → Applications → App registrations
3. Click New registration
4. Configure:

Entra ID Field	Value
Name	Zenovay
Supported account types	Accounts in this organizational directory only
Redirect URI	Web — https://auth.zenovay.com/api/sso/oauth/callback

5. Click Register

Step 2: Create Client Secret

1. Go to Certificates & secrets
2. Click New client secret
3. Set description and expiration
4. Copy the secret value immediately (it will not be shown again)

Step 3: Note Application Details

Record these values:

• Application (client) ID — from the Overview page
• Client Secret — from Step 2
• Tenant ID — from the Overview page

Step 4: API Permissions

1. Go to API permissions
2. Verify Microsoft Graph → User.Read (delegated) is listed
3. If not, click Add a permission → Microsoft Graph → Delegated permissions → User.Read

Step 5: Configure in Zenovay

1. Go to Settings → Authentication → SSO
2. Click Add SSO Provider and select OpenID Connect
3. Enter:
   • Name: e.g., "Microsoft Entra ID"
   • Client ID: the Application (client) ID from Step 3
   • Client Secret: the secret value from Step 2
   • Issuer URL: https://login.microsoftonline.com/{your-tenant-id}/v2.0
4. Click Save
5. Add and verify your email domain
6. Test the connection

Okta OIDC Setup

Step 1: Create Application

1. Go to Okta Admin Console → Applications
2. Click Create App Integration
3. Select OIDC - OpenID Connect
4. Select Web Application
5. Click Next

Step 2: Configure Application

Okta Field	Value
App integration name	Zenovay
Grant type	Authorization Code
Sign-in redirect URIs	https://auth.zenovay.com/api/sso/oauth/callback

Step 3: Assign Users

1. Go to the Assignments tab
2. Assign users or groups
3. Save

Step 4: Get Credentials

From the General tab, note:

• Client ID
• Client Secret

Step 5: Get Issuer URL

1. Go to Security → API in the Okta Admin Console
2. Find your authorization server (usually "default")
3. The Issuer URI will look like: https://your-org.okta.com/oauth2/default

Step 6: Configure in Zenovay

1. Go to Settings → Authentication → SSO
2. Click Add SSO Provider and select OpenID Connect
3. Enter:
   • Name: e.g., "Okta"
   • Client ID: from Step 4
   • Client Secret: from Step 4
   • Issuer URL: from Step 5
4. Click Save
5. Add and verify your email domain
6. Test the connection

Auth0 Setup

Step 1: Create Application

1. Go to Auth0 Dashboard
2. Go to Applications → Create Application
3. Choose Regular Web Applications
4. Click Create

Step 2: Configure Settings

In the Settings tab:

Auth0 Field	Value
Allowed Callback URLs	https://auth.zenovay.com/api/sso/oauth/callback

Click Save Changes.

Step 3: Get Credentials

From the Settings tab, note:

• Domain (e.g., your-tenant.us.auth0.com)
• Client ID
• Client Secret

Step 4: Configure in Zenovay

1. Go to Settings → Authentication → SSO
2. Click Add SSO Provider and select OpenID Connect
3. Enter:
   • Name: e.g., "Auth0"
   • Client ID: from Step 3
   • Client Secret: from Step 3
   • Issuer URL: https://your-tenant.us.auth0.com/ (include trailing slash)
4. Click Save
5. Add and verify your email domain
6. Test the connection

Google Workspace

If you specifically need OIDC with Google, you can create OAuth credentials in the Google Cloud Console:

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Select Web application and enter https://auth.zenovay.com/api/sso/oauth/callback as the redirect URI
4. Note the Client ID and Client Secret
5. In Zenovay, add an OpenID Connect provider with Issuer URL: https://accounts.google.com

Custom OIDC Provider

If your identity provider supports OpenID Connect Discovery:

1. Go to Settings → Authentication → SSO
2. Click Add SSO Provider and select OpenID Connect
3. Enter:
   • Name: your provider name
   • Client ID: from your IdP
   • Client Secret: from your IdP
   • Issuer URL: your IdP's issuer URL (e.g., https://your-idp.com)
4. Click Save

Zenovay will automatically discover your IdP's authorization, token, userinfo, and JWKS endpoints via the .well-known/openid-configuration document.

Custom OAuth 2.0 Provider

If your identity provider does not support OIDC auto-discovery, use OAuth 2.0 with manual endpoint configuration:

1. Go to Settings → Authentication → SSO
2. Click Add SSO Provider and select OAuth 2.0
3. Enter:
   • Name: your provider name
   • Client ID: from your IdP
   • Client Secret: from your IdP
   • Authorization URL: your IdP's authorization endpoint
   • Token URL: your IdP's token endpoint
   • User Info URL: your IdP's user info endpoint
4. Click Save

Completing Setup

Verify Domain

After saving your SSO provider:

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

Test Connection

1. Open an incognito/private browser window
2. Go to auth.zenovay.com
3. Enter an email from your verified domain
4. Authenticate with your IdP
5. Verify successful return to the Zenovay dashboard

Enable SSO

1. Toggle Enforce SSO to on
2. Set enforcement:
   • Optional: users can choose SSO or password login
   • Required: all users must use SSO
3. Save configuration

User Attribute Mapping

Standard Claims

OIDC Claim	Zenovay Field
email	Email address
given_name	First name
family_name	Last name
sub	Unique identifier

Just-In-Time Provisioning

Auto-Create Users

New users are automatically created on first SSO login:

• Automatic account creation
• Default role assigned (Viewer)
• No invitation needed

Security Features

Zenovay automatically applies these security measures for OAuth/OIDC:

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

Troubleshooting

Common Errors

Error	Cause	Solution
Invalid redirect_uri	URL mismatch	Ensure redirect URI is exactly https://auth.zenovay.com/api/sso/oauth/callback
Invalid client_id	Wrong credential	Verify client ID in your IdP dashboard
Invalid grant	Code expired	Try again — authorization codes are short-lived
Token verification failed	Signature failure	Verify JWKS endpoint is accessible
State parameter mismatch	Session issue	Clear cookies and try in an incognito window
OIDC discovery failed	Issuer URL issue	Test {issuer-url}/.well-known/openid-configuration in your browser

Certificate Issues

If JWKS fails:

• Check JWKS URL is accessible
• Verify SSL certificate is valid
• Check for firewall blocks

Security Considerations

Secret Management

• Store client secret securely
• Rotate secrets before they expire
• Never expose secrets in client-side code

Scope Limitations

Request minimal scopes:

• Only openid, email, profile
• Don't request unnecessary access

Redirect URI Validation

• Use exact match validation in your IdP
• Don't use wildcards
• HTTPS required

Next Steps

• Enforce MFA for all users
• Configure audit logging
• Custom password policies