Concepts

Zenskar supports single sign-on (SSO) through SAML 2.0. An organization can let its people sign in to Zenskar with the accounts they already have at an identity provider, instead of a separate Zenskar login. Microsoft Entra ID, Google Workspace, and Okta are supported, configured from Settings > SAML. The per-provider how-to guides cover the setup steps; this page explains how it works.

​

What single sign-on changes

Authentication moves to the identity provider. While SAML is enabled for a verified email domain, the identity provider decides who can sign in to Zenskar with an address at that domain. Access is granted and revoked at the identity provider: removing someone there stops their Zenskar sign-in immediately, with no matching change in Zenskar. People no longer set or manage a Zenskar password. Authorization stays in Zenskar. Roles and permissions remain in Zenskar’s role-based access control, and Zenskar does not read groups or roles from the identity provider. Provisioning also stays in Zenskar. A person still needs a Zenskar user record with a role assigned. With SAML active, creating that record no longer sends a password-setup email; the person’s sign-in identity is created from their first SAML assertion instead. Someone who already had a Zenskar password confirms it once, on their first SSO sign-in, to link their existing account.

​

How trust is established

SAML connects two parties: the identity provider (IdP), which authenticates the user, and the service provider (SP), which is Zenskar. They trust each other through a one-time exchange of identifiers and a signing certificate. The identity provider is given Zenskar’s Entity ID and ACS URL, so it knows which service is asking and where to return the response. Zenskar is given the identity provider’s issuer, sign-in URL, and X.509 certificate, so it can recognize the identity provider and confirm that every assertion was signed by it and not altered in transit. If the identity provider rotates its certificate, the new one has to be entered in Zenskar or sign-in stops. These values are entered on Settings > SAML, along with a mapping from four Zenskar fields (user ID, email, first name, last name) to the attributes the assertion carries. The reference lists every field.

​

How a sign-in works

Zenskar does not render its own login form. It delegates authentication to a hosted identity platform, and a user without a valid session is redirected to that platform’s sign-in page. What happens next depends on the domain of the email address entered:

• If the domain has no SAML configuration, or the domain is not yet verified, the user gets a standard email-and-password sign-in.
• If the domain’s SAML configuration is verified, the user is redirected to the organization’s identity provider to authenticate there, then returned to Zenskar.

Sign-in always begins on the Zenskar side. Opening Zenskar from a tile or link inside the identity provider does not complete sign-in, and the user is sent back to the Zenskar sign-in page to start again. For users who sign in through SAML, multi-factor authentication is enforced by the identity provider, and Zenskar adds no second prompt of its own.

​

Domain verification

A SAML configuration takes effect only for an email domain the organization has proven it controls. Zenskar issues a DNS TXT record for the domain; once that record is in place and Zenskar has confirmed it, the domain’s status becomes Verified. Verification is what routes sign-ins. An unverified domain falls back to email-and-password sign-in even when every other value has been filled in and SAML is switched on. Configure the identity provider after the domain shows as Verified.

​

What SAML does not cover

• Provisioning and roles. Zenskar does not create users or assign roles from the assertion. User records and role-based access control are managed in Zenskar.
• Single logout. Signing out of Zenskar ends the Zenskar session only. It does not end the session at the identity provider.
• Identity-provider-initiated sign-in. Every sign-in has to start at the Zenskar sign-in page.
• Per-user or per-entity scope. A configuration applies to everyone signing in with an address at the verified domain.
• Multiple email domains. A configuration covers one verified domain. With acme.com verified, user@acme.com is routed to the identity provider and user@acme.co.uk falls back to email-and-password.

​

Scope

An organization has one SAML configuration, for a single verified email domain, applied across the whole organization rather than per business entity. The configuration is held against the production organization, and sandbox access uses the same one.

​

Set up SAML for your provider