Single Sign-On (SSO)
Configure Single Sign-On (SSO) authentication for ZenML Pro self-hosted deployments.
This guide covers Single Sign-On (SSO) configuration for ZenML Pro self-hosted deployments. SSO allows users to authenticate through an external identity provider instead of using local accounts with password authentication.
SSO configuration is only applicable to the fully self-hosted scenario. The hybrid scenario uses the ZenML Pro SaaS SSO for authentication.
Overview
By default, the ZenML Pro control plane uses local accounts with password authentication. Enabling SSO provides several benefits:
Centralized user management: Users are managed in your identity provider, not in ZenML Pro
Enhanced security: Leverage your organization's existing authentication policies (MFA, password policies, etc.)
Simplified access: Users authenticate with credentials they already know
Automated provisioning: ZenML Pro user accounts are created automatically on first login
You can start with local accounts and enable SSO later without losing existing data. SSO and password authentication can also be enabled simultaneously during a transition period.
SSO Prerequisites
Supported Identity Providers
Any OIDC-compatible identity provider can be used, including:
Cloud identity services
Google Workspace, Microsoft Entra ID (Azure AD), Okta, Auth0
Self-hosted solutions
Keycloak, Authentik, Dex, Gluu
Enterprise directories
ADFS, Ping Identity, OneLogin
Identity Provider Requirements
Your identity provider must meet the following specifications:
OAuth 2.0 authorization code flow
Must support the standard authorization code grant
JWT ID token
Must issue JWT ID tokens during the authorization code flow
Required scopes
openid, email, profile
OpenID configuration endpoint
Must expose /.well-known/openid-configuration at a URL reachable by the ZenML Pro control plane
JWKS
Must implement JSON Web Key Set for signing ID tokens
Logout endpoint (optional)
If supported, enables single logout functionality
ZenML Pro Client Configuration in the Identity Provider
When registering ZenML Pro as an OIDC client in your identity provider, configure the following:
Redirect URI
https://<zenml-ui-url>/api/auth/callback
Post-logout redirect URI
https://<zenml-ui-url>/api/auth/logout-complete (if logout is supported)
Allowed scopes
openid, email, profile
Client type
Confidential (requires client secret)
After registration, your identity provider will issue a client ID and client secret that you will need when configuring ZenML Pro, in addition to the URL to the OpenID configuration endpoint (/.well-known/openid-configuration).
Information to Collect
Before configuring SSO, gather the following information from your identity provider:
Identity provider
_______________ (e.g., Okta, Azure AD, Keycloak)
OIDC discovery URL
_______________ (e.g., https://idp.example.com/.well-known/openid-configuration)
Client ID
_______________
Client secret
_______________
Redirect URI (configured in IdP)
https://<web-ui-url>/api/auth/callback
Post-logout redirect URI (if applicable)
https://<web-ui-url>/api/auth/logout-complete
IDP logout URI to call (if applicable)
https://<idp-url>/v2/logout
Configuring SSO
SSO is configured differently depending on your deployment method. Refer to the deployment guide for your chosen infrastructure:
Control Plane Kubernetes Deployment — SSO configuration via Helm values
Migrating from Password Authentication to SSO
If you have an existing ZenML Pro deployment using local accounts with password authentication, you can migrate to SSO authentication while preserving all existing resources and their ownership. This section describes the recommended migration process.
Migration Overview
The migration process involves running both authentication methods simultaneously during a transition period, then disabling password authentication once all users have migrated to SSO. During this period:
Existing local users continue to have access to their resources
New SSO users can be invited and granted permissions
Resource ownership can be transferred if needed
Step 1: Enable SSO While Keeping Password Authentication
Update your ZenML Pro control plane configuration to enable SSO authentication while keeping password authentication enabled. This allows both authentication methods to work simultaneously.
Do not disable password authentication at this stage. Doing so would lock out all existing local user accounts immediately.
The specific configuration depends on your deployment method. Refer to your deployment guide for details on how to enable SSO.
Step 2: Log In with a Local User Account
After enabling SSO, log in to the ZenML Pro UI using an existing local user account that has administrative privileges (e.g., a super-user account or an organization owner).
This account will be used to invite SSO users and grant them the necessary permissions to manage the organization and its resources.
Step 3: Invite SSO Users to Organizations
While logged in with the local user account, invite the SSO users who will take over management of the organization:
Navigate to Organization Settings → Members
Click Invite Member
Enter the email address of the SSO user (this should match the email address in your identity provider)
Assign appropriate roles (e.g., Organization Owner, Organization Admin)
Repeat for all SSO users who need access
The invited users don't need to exist in ZenML Pro yet. Their accounts will be created automatically when they first log in via SSO and accept the invitation.
Step 4: SSO Users Accept Invitations
Each invited SSO user should:
Access the ZenML Pro UI
Log in using the SSO authentication flow (click "Sign in with SSO" or similar)
After authentication, accept any pending organization invitations
Once an SSO user accepts an invitation, they have full access to the organization according to their assigned roles.
Step 5: Transfer Resource Ownership (Optional)
If local users own resources that should be transferred to SSO users, you can update the ownership through the UI or API. This step is optional—resources owned by local users remain accessible to organization members based on their roles even after disabling password authentication.
Resource ownership primarily affects who can delete or transfer resources. Organization members with appropriate roles can still view and use resources owned by other users within the organization.
Step 6: Disable Password Authentication
Once all SSO users have been invited, have accepted their invitations, and have verified they can access all necessary resources, you can disable password authentication.
Disabling password authentication will immediately lock out all local user accounts. Ensure all users who need access have successfully authenticated via SSO before proceeding.
Update your ZenML Pro control plane configuration to disable password authentication. The specific configuration depends on your deployment method.
After disabling password authentication:
Local user accounts can no longer log in
Resources owned by local users remain in the system and are accessible to organization members
The admin account used for initial setup is also disabled
Only SSO authentication is available
Rollback Procedure
If you need to re-enable password authentication after disabling it:
Update your ZenML Pro control plane configuration to re-enable password authentication
Local user accounts will be able to log in again with their original passwords
Local user account passwords are preserved in the database even when password authentication is disabled. Re-enabling password authentication restores access without requiring password resets.
Troubleshooting
Common SSO Issues
"Invalid redirect URI" error
Redirect URI in ZenML Pro doesn't match the one configured in your IdP
Verify the redirect URI matches exactly, including the protocol (https)
Users can't log in after SSO is enabled
OIDC discovery URL is not reachable from the ZenML Pro control plane
Check network connectivity and firewall rules
User email doesn't match invitation
Email claim in the ID token differs from the invited email
Verify the email address format in your IdP matches what was invited
SSO login works but user has no access
User hasn't accepted organization invitation
User should check for pending invitations after logging in
Verifying SSO Configuration
Before disabling password authentication, verify that SSO is working correctly:
Open an incognito/private browser window
Navigate to the ZenML Pro UI
Attempt to log in using SSO
Verify you can access the expected organizations and resources
Synchronizing SSO Users with External Directories
When using SSO authentication, ZenML Pro creates user accounts automatically on first login. However, ZenML Pro does not automatically synchronize user roles, group memberships, or other attributes from your identity provider.
ZenML Pro does not consume roles, groups, or other claims from OIDC ID tokens. All ZenML Pro roles, team memberships, and organization assignments must be configured within ZenML Pro.
To maintain consistency between your identity provider and ZenML Pro, you can implement automated synchronization using the ZenML Pro API.
Invitations as User Placeholders
A key concept for synchronization is that invitations act as placeholders for user accounts before users log in via SSO:
You can create an invitation for an email address before the user has ever logged in
Invitations can be assigned organization roles, workspace roles, project roles, and team memberships—just like user accounts
When the user logs in via SSO and accepts the invitation, all permissions linked to the invitation are automatically transferred to their newly created user account
This allows you to pre-provision access for users based on their IdP group memberships, even before they've logged into ZenML Pro for the first time.
Synchronization Architecture
A typical synchronization workflow involves:
Fetch users from IdP: Query your identity provider for users, their groups, and roles
Map to ZenML Pro concepts: Define how IdP groups/roles map to ZenML Pro organizations, teams, and roles
Synchronize via API:
For users who have logged in: update their user accounts directly
For users who haven't logged in yet: create invitations and assign permissions to them
Run periodically: Execute the synchronization on a schedule (e.g., via cron, Kubernetes CronJob, or CI/CD pipeline)
Mapping Conventions
Define a mapping strategy that works for your organization. Understanding ZenML Pro's hierarchy is essential for effective mapping:
ZenML Pro Resource Hierarchy:
Organizations contain workspaces and teams
Teams are organization-local (each team belongs to exactly one organization)
Roles are scoped to specific levels:
Organization-level roles (e.g., Organization Admin, Organization Member)
Workspace-level roles (e.g., Workspace Admin, Workspace Developer)
Project-level roles (e.g., Project Admin, Project Viewer)
See Roles & Permissions for the full list of predefined roles at each level.
Common Mapping Approaches:
By Organization
Group membership
Organization membership + role
zenml-org-<org-id>-admin → Org Admin in specific org
By Team
Group membership
Team membership (within an org)
zenml-team-<org-id>-<team-id> → Team in specific org
By Workspace
Group membership
Workspace role assignment
zenml-ws-<workspace-id>-developer → Workspace Developer
By Project
Group membership
Project role assignment
zenml-proj-<project-id>-viewer → Project Viewer
Global Admin
Role/attribute
Organization Admin in all orgs
zenml-global-admin → Admin across organizations
Example Mapping with UUIDs:
Alternative: Human-Readable Mapping with Configuration File:
Instead of embedding UUIDs in group names, maintain a separate mapping configuration:
This approach keeps IdP group names human-readable while the synchronization script resolves them to ZenML Pro UUIDs.
Programmatic API Access
To synchronize users programmatically, authenticate using either a Personal Access Token or a Service Account API key. Service accounts are recommended for automated synchronization jobs.
For detailed API documentation, see:
Interactive OpenAPI documentation at
https://<zenml-pro-url>/api/v1
Key API Patterns
Before reviewing the script, note these important ZenML Pro API patterns:
Add user to organization
Assign an organization-level role via POST /roles/{role_id}/assignments?user_id={id}
Add invitation to organization
Create invitation via POST /organizations/{org_id}/invitations with a role
Assign additional roles
POST /roles/{role_id}/assignments with user_id, invitation_id, or team_id
Add user/invitation to team
POST /teams/{team_id}/members?user_id={id} or ?invitation_id={id}
Remove user from organization
DELETE /organizations/{org_id}/members?user_id={id}
Revoke role
DELETE /roles/{role_id}/assignments with appropriate query params
Example Synchronization Script
We provide a complete example synchronization script that demonstrates how to:
Fetch users from an IdP (with a placeholder for your IdP implementation)
Map IdP groups to ZenML Pro organizations, teams, and roles
Handle both existing users and users who haven't logged in yet (via invitations)
Use the ZenML Pro API correctly for all operations
Script highlights:
IdPClient
Placeholder class for your IdP integration (Okta, Azure AD, Keycloak, etc.)
ZenMLProClient
Complete API client for ZenML Pro with methods for users, organizations, invitations, roles, and teams
UserSynchronizer
Orchestrates the sync, handling both existing users and pre-provisioning via invitations
Key features:
Dual-mode synchronization: Syncs directly to user accounts for users who have logged in, creates invitations for users who haven't
Caching: Reduces API calls by caching organizations, roles, and teams
Error handling: Gracefully handles conflicts (e.g., role already assigned) and logs errors
Configurable mapping: Easy-to-modify mapping dictionaries for your organization's group naming conventions
Running the Synchronization
Manual execution:
Kubernetes CronJob:
Related Resources
Last updated
Was this helpful?