SAML 2.0 SSO Configuration

Scale Plan

Configure SAML 2.0 single sign-on to allow your team to access Zenovay using your organization's identity provider.

Supported Identity Providers

Provider	Status
Okta	Fully Supported
Microsoft Entra ID (Azure AD)	Fully Supported
OneLogin	Fully Supported
Google Workspace	Fully Supported
Ping Identity	Fully Supported
ADFS	Fully Supported
Custom SAML 2.0	Supported

Prerequisites

Before starting:

• Scale or Enterprise plan activated
• Admin access to your identity provider
• Owner or Admin access to Zenovay
• Your organization's email domain ready to verify

Zenovay SAML Information

Service Provider Details

You will need these values when configuring the SAML application in your identity provider. Each workspace gets its own Entity ID, so the exact values are shown in Zenovay under Settings → Security → SSO in the Service Provider Details section. The format is:

Setting	Value
SP Entity ID / Audience URI	https://auth.zenovay.com/sso/{teamId}
ACS URL (Assertion Consumer Service)	https://auth.zenovay.com/api/sso/saml/callback
Metadata URL	https://auth.zenovay.com/api/sso/metadata/{teamId}
NameID Format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Binding	HTTP-POST

Most identity providers can also import the Metadata URL above to fill in the Entity ID and ACS URL automatically.

Getting Your Values

1. Go to Settings → Security → SSO
2. The Service Provider Details section lists your Entity ID, ACS URL, and OAuth/OIDC redirect URI. Use the copy button next to each value.
3. Click Add provider and select SAML to start configuring your IdP.

Okta Configuration

Step 1: Create Okta Application

1. Log in to Okta Admin Console
2. Go to Applications → Applications
3. Click Create App Integration
4. Select SAML 2.0
5. Click Next

Step 2: Configure SAML Settings

General Settings:

• App name: Zenovay
• App logo: Upload Zenovay logo (optional)

SAML Settings (copy the exact Single sign-on URL and Audience URI from Settings → Security → SSO in Zenovay):

Okta Field	Value
Single sign-on URL	https://auth.zenovay.com/api/sso/saml/callback
Audience URI (SP Entity ID)	https://auth.zenovay.com/sso/{teamId}
Name ID format	EmailAddress
Application username	Email

Step 3: Attribute Statements

Add these attribute mappings:

Name	Value
email	user.email
firstName	user.firstName
lastName	user.lastName

Step 4: Get IdP Values

1. Go to the Sign On tab
2. Click View SAML setup instructions or Identity Provider metadata
3. Note the following:
   • IdP Entity ID (Issuer)
   • IdP SSO URL (Login URL)
4. Download the X.509 Certificate

Step 5: Complete in Zenovay

1. Go to Settings → Security → SSO
2. Click Add provider and select SAML
3. Enter:
   • Name: e.g., "Okta"
   • Entity ID: the IdP Entity ID from Step 4
   • SSO URL: the IdP SSO URL from Step 4
   • Certificate: paste the full X.509 certificate
4. Click Create
5. Add and verify your email domain
6. Use the provider's Test connection action to confirm it works

Microsoft Entra ID Configuration

Step 1: Create Enterprise Application

1. Sign in to the Microsoft Entra admin center
2. Go to Identity → Applications → Enterprise applications
3. Click New application
4. Click Create your own application
5. Name: Zenovay
6. Select Integrate any other application you don't find in the gallery

Step 2: Set Up Single Sign-On

1. Click Single sign-on in the sidebar
2. Select SAML
3. Edit Basic SAML Configuration (copy the exact values from Settings → Security → SSO in Zenovay):

Entra ID Field	Value
Identifier (Entity ID)	https://auth.zenovay.com/sso/{teamId}
Reply URL (ACS URL)	https://auth.zenovay.com/api/sso/saml/callback

Step 3: Configure Attributes

Edit Attributes & Claims:

Claim Name	Source Attribute
emailaddress	user.mail
givenname	user.givenname
surname	user.surname

Ensure the NameID claim format is set to Email address.

Step 4: Download Certificate and Get IdP Values

1. Scroll to SAML Signing Certificate and download Certificate (Base64)
2. In the Set up Zenovay section, copy:
   • Microsoft Entra Identifier — this is your IdP Entity ID
   • Login URL — this is your SSO URL

Step 5: Assign Users

1. Go to Users and groups
2. Add users or groups
3. Save assignments

Step 6: Complete in Zenovay

1. Go to Settings → Security → SSO
2. Click Add provider and select SAML
3. Enter:
   • Name: e.g., "Microsoft Entra ID"
   • Entity ID: the Microsoft Entra Identifier from Step 4
   • SSO URL: the Login URL from Step 4
   • Certificate: paste the contents of the downloaded Base64 certificate
4. Click Create
5. Add and verify your email domain
6. Use the provider's Test connection action to confirm it works

Google Workspace Configuration

Step 1: Add Custom SAML App

1. Go to Google Admin Console
2. Go to Apps → Web and mobile apps
3. Click Add App → Add custom SAML app

Step 2: Enter Details

App details:

• App name: Zenovay
• Description: Analytics platform
• App icon: Upload (optional)

Step 3: Download IdP Metadata

1. Copy or download the SSO URL and Entity ID
2. Download the Certificate
3. Click Continue

Step 4: Service Provider Details

Copy the exact ACS URL and Entity ID from Settings → Security → SSO in Zenovay:

Google Admin Field	Value
ACS URL	https://auth.zenovay.com/api/sso/saml/callback
Entity ID	https://auth.zenovay.com/sso/{teamId}
Name ID format	EMAIL
Name ID	Basic Information > Primary email

Step 5: Attribute Mapping

Google Directory	App Attribute
Primary email	email
First name	firstName
Last name	lastName

Step 6: Enable for Users

1. Click on the app
2. Go to User access section
3. Turn ON for your organization or specific organizational units

Step 7: Complete in Zenovay

1. Go to Settings → Security → SSO
2. Click Add provider and select SAML
3. Enter the IdP Entity ID, SSO URL, and Certificate from Step 3
4. Click Create
5. Add and verify your email domain
6. Use the provider's Test connection action to confirm it works

OneLogin Configuration

Step 1: Add Application

1. Go to OneLogin Admin
2. Go to Applications → Add App
3. Search SAML Custom Connector (Advanced)
4. Add

Step 2: Configuration Tab

Copy the exact Audience and Recipient/ACS values from Settings → Security → SSO in Zenovay:

OneLogin Field	Value
Audience (EntityID)	https://auth.zenovay.com/sso/{teamId}
Recipient	https://auth.zenovay.com/api/sso/saml/callback
ACS (Consumer) URL	https://auth.zenovay.com/api/sso/saml/callback

Step 3: Parameters

Add parameters:

Field	Value
email	Email
firstName	First Name
lastName	Last Name

Step 4: SSO Tab

Note the following values:

• SAML 2.0 Endpoint (HTTP)
• Issuer URL
• Download the X.509 Certificate

Step 5: Complete in Zenovay

1. Go to Settings → Security → SSO
2. Click Add provider and select SAML
3. Enter the IdP values from Step 4
4. Click Create
5. Add and verify your email domain

Completing Setup in Zenovay

Add SSO Provider

1. Go to Settings → Security → SSO
2. Click Add provider
3. Select SAML
4. Enter the following values from your identity provider:

Field	Description
Name	A friendly name for this provider (e.g., "Corporate Okta")
Entity ID	The IdP Entity ID / Issuer from your identity provider
SSO URL	The IdP Login URL / SSO Endpoint
SLO URL	The IdP Single Logout URL (optional)
Certificate	The X.509 signing certificate (paste full PEM including BEGIN/END lines)

5. Click Create

Verify Domain

After saving, add and verify your email domain:

1. Enter your email domain (e.g., company.com) in the Domain Verification section
2. Click Verify domain
3. Add the TXT record shown to your domain's DNS, then click Check DNS
4. Once verified, users with that domain are directed to SSO at sign-in

Test Connection

1. Open the provider's More menu and choose Test connection, or test the login flow directly:
2. Open an incognito/private browser window
3. Go to auth.zenovay.com
4. Enter an email from your verified domain
5. Authenticate with your IdP
6. Verify successful return to the Zenovay dashboard

Enforce SSO

After a successful test, you can require SSO so users can no longer sign in with a password:

1. Make sure the provider is enabled (the toggle next to it)
2. Open the provider's More menu and select Enforce SSO
3. Confirm in the dialog

User Provisioning

Just-In-Time (JIT) Provisioning

New users are created automatically on their first successful SSO login:

• The account is created from the email and name in the SAML assertion
• No invitation email is required

Troubleshooting

Common Issues

Issue	Solution
"Signature verification failed"	Re-download the IdP certificate and update it in Zenovay
"Digest mismatch"	Ensure the correct signing certificate is configured
"SSO is not configured for your domain"	Add and verify the user's email domain in the SSO settings
"ACS URL mismatch"	Ensure the ACS URL is exactly https://auth.zenovay.com/api/sso/saml/callback
"Entity ID mismatch"	Ensure the Audience/Entity ID matches the value shown in Settings → Security → SSO (it ends in your team ID)
"NameID not found"	Set NameID format to EmailAddress in your IdP

Certificate Expiration

IdP certificates expire — plan ahead:

1. Monitor expiration dates in your IdP
2. Download the new certificate before expiration
3. Edit the SSO provider in Zenovay and replace the certificate
4. Test the connection with the new certificate

Security Best Practices

Certificate Management

• Monitor expiration dates
• Use SHA-256 signing
• Update certificates before they expire

Attribute Security

• Only request needed attributes
• Verify attribute mappings
• Monitor for changes

Access Control

• Assign specific users/groups in your IdP
• Review access regularly
• Use conditional access policies

Next Steps

• Set up OAuth/OIDC
• Enforce MFA
• Configure audit logging