Single Sign-On

Single Sign-On (SSO) hands authentication off to the identity provider (IdP) your company already runs — Microsoft Entra ID, Google Workspace, Okta, ADFS, and anything else that speaks OpenID Connect or SAML 2.0. Instead of every teammate maintaining a separate Zelaxy password, they authenticate once against your directory and land straight in their workspace.

Zelaxy stores one provider record per email domain. When someone signs in, their domain decides which IdP handles the request.

The sign-in flow

Here is what happens end to end once a provider is live:

First-time sign-ins are provisioned automatically at the member role — no invite step — as long as organizations are enabled on the deployment. Email and password login keeps working alongside SSO; Zelaxy does not currently force a domain onto SSO exclusively.

Before you begin

Who is allowed to configure SSO depends on how Zelaxy is running:

You also need admin access to your identity provider so you can register an application and copy its credentials.

Add a provider

Everything is configured from Hub → Settings → Single Sign-On (under the Organization group).

https://app.zelaxy.in/api/auth/sso/callback/<provider-id>

https://app.zelaxy.in/api/auth/sso/saml2/callback/<provider-id>

Field reference

OIDC

Zelaxy resolves the authorization, token, userinfo, and JWKS endpoints from the issuer's /.well-known/openid-configuration document, so you never enter them by hand.

SAML 2.0

Connect your identity provider

Linking to existing accounts

When a person signs in through SSO and an account already exists for that email — say they signed up earlier with a password — Zelaxy links the two automatically, provided the IdP marks the email as verified (email_verified) or the provider is trusted. Mainstream OIDC providers assert this claim, so linking is transparent.

Some IdPs, mostly on the SAML side, leave the claim out. In that case, trust the provider explicitly by adding its Provider ID to SSO_TRUSTED_PROVIDER_IDS (self-hosted) and restarting. Without it, sign-in fails with an account not linked error.

Self-hosting

Self-hosted deployments swap the plan check for environment variables.

# Turn SSO on
SSO_ENABLED=true
NEXT_PUBLIC_SSO_ENABLED=true

# Enable organizations so SSO users are added to your org on first sign-in
ORGANIZATIONS_ENABLED=true
NEXT_PUBLIC_ORGANIZATIONS_ENABLED=true

# Trust extra providers for automatic account linking (comma-separated Provider IDs).
# Use when your IdP omits email_verified — typically SAML.
SSO_TRUSTED_PROVIDER_IDS=partner-saml,legacy-oidc

Make sure the schema is up to date so the sso_provider table exists:

cd apps/zelaxy && bun run db:push   # or apply the 0009_sso_provider migration

Providers can be created from the same Settings UI, or seeded from the command line — handy for first-boot automation and CI.

Register an OIDC provider

SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://your-instance.com \
SSO_PROVIDER_TYPE=oidc \
SSO_PROVIDER_ID=okta \
SSO_ISSUER=https://your-org.okta.com/oauth2/default \
SSO_DOMAIN=company.com \
SSO_USER_EMAIL=admin@company.com \
SSO_OIDC_CLIENT_ID=your-client-id \
SSO_OIDC_CLIENT_SECRET=your-client-secret \
bun run apps/zelaxy/scripts/register-sso-provider.ts

Register a SAML provider

SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://your-instance.com \
SSO_PROVIDER_TYPE=saml \
SSO_PROVIDER_ID=adfs \
SSO_ISSUER=https://your-instance.com \
SSO_DOMAIN=company.com \
SSO_USER_EMAIL=admin@company.com \
SSO_SAML_ENTRY_POINT=https://adfs.company.com/adfs/ls \
SSO_SAML_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
bun run apps/zelaxy/scripts/register-sso-provider.ts

The SSO_USER_EMAIL account has to exist already — it becomes the owner of the provider record. On success the script prints the callback URL to hand to your IdP.

Remove a provider

SSO_USER_EMAIL=admin@company.com \
SSO_PROVIDER_ID=okta \
bun run apps/zelaxy/scripts/deregister-sso-provider.ts

Drop SSO_PROVIDER_ID to remove every provider owned by that user.

Troubleshooting