Reference

This page documents Zenskar’s SAML implementation: the fields on Settings > SAML, what is checked when the configuration is saved, how domain verification works, and the SAML assertion Zenskar expects from an identity provider.

SAML tab fields

The SAML tab has four sections.

Connection

Field	Notes
Name	A label for this configuration. Up to 100 characters.
Domain	The organization’s email domain. One domain per configuration. Bare domain only, no scheme and no path.
Identity Provider	Google Workspace, Microsoft Entra ID, or Okta. Defaults to Google Workspace.
SAML Status	Turns the connection on or off. The identity provider connection is applied only while this is on. See Applying changes.
TXT Records	The generated host name and value for domain verification, with the VERIFY DOMAIN action.

Identity Provider Configuration

Field	Notes
Entity ID field	Labelled Identity Provider Entity ID (Google Workspace), Microsoft Entra Identifier (Microsoft Entra ID), or Identity Provider Issuer (Okta). The identity provider’s entity ID or issuer URI.
Single sign-on URL field	Labelled Single Sign-On Service URL (Google Workspace), Login URL (Microsoft Entra ID), or Identity Provider Single Sign-On URL (Okta). Must use `https`.
Certificate	The identity provider’s X.509 signing certificate, PEM format, a single block.

Attribute Mapping

Field	Notes
User ID	Name of the assertion attribute carrying the user identifier. Default `id`.
Email address	Name of the assertion attribute carrying the email address. Default `mail`.
First name	Name of the assertion attribute carrying the given name. Default `firstName`.
Last name	Name of the assertion attribute carrying the surname. Default `lastName`.

Zenskar SAML Configuration Values

Field	Notes
Entity ID	Zenskar’s SP entity ID. The same value for every organization.
ACS URL	Zenskar’s Assertion Consumer Service URL. Unique per organization and per selected identity provider. Shown once an identity provider is selected.

Field validation

Checked when Save Configuration is clicked.

Field	Rule
Name	Up to 100 characters.
Domain	A valid domain such as `acme.com`. No `http://` or `https://`, no path.
Entity ID / Issuer	An absolute URI. `http://` is accepted, because Okta issues an `http://` issuer.
Single sign-on URL	A valid URL that uses `https`.
Certificate	Exactly one PEM certificate block, with nothing outside the BEGIN and END lines, whose body is valid Base64 that decodes to a valid X.509 structure. A certificate chain or more than one block is rejected.
Attribute mappings	No spaces.
All fields above	Required when SAML Status is on. While SAML Status is off, an incomplete configuration can be saved, but any value that is filled in is still format-checked.

Zenskar’s SAML values

Value	Form
Entity ID	`https://auth.zenskar.com/auth/realms/zenskar`
ACS URL	`https://auth.zenskar.com/auth/realms/zenskar/broker/<organization-id>-<provider>/endpoint`, where `<provider>` is `google-workspace`, `microsoft-entra-id`, or `okta`

Copy both from the SAML tab rather than constructing them. The ACS URL uses the production organization’s ID.

Domain verification

Zenskar issues a DNS TXT record to prove control of the email domain.

Part	Value
Host name	`zenskar-verify.<domain>`
Value	`zenskar-verify=<token>`, where `<token>` is 32 hexadecimal characters

VERIFY DOMAIN queries DNS for that TXT record and sets the status to Verified when the value is found. Otherwise the status stays Pending.

Status	Meaning
Pending	TXT record requested, not yet found in DNS.
Verified	TXT record found.

Sign-in routes to the identity provider only for a Verified domain. An unverified domain falls back to email-and-password sign-in even when the rest of the configuration is filled in and SAML Status is on.

The SAML assertion Zenskar expects

Property	Requirement
NameID format	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. The NameID must be the user’s email address.
Bindings	Zenskar sends its AuthnRequest and expects the response by HTTP-POST.
AuthnRequest signing	Not required. Zenskar does not sign its AuthnRequests.
Response signing	Validated against the configured certificate. With no certificate configured, signature validation is off.
Assertion encryption	Not supported.
Clock skew tolerance	5 seconds.
Single logout (SLO)	Not configured. Signing out of Zenskar does not sign the user out of the identity provider.
Attributes	The assertion should carry the four attributes named in Attribute Mapping. Zenskar reads the given name and surname from them to populate the user’s profile on first sign-in.

Sign-in is SP-initiated. Users must start at the Zenskar sign-in page. Starting from a tile or deep link inside the identity provider does not complete sign-in.

Applying changes

The identity provider connection is created or updated only when the configuration is saved with SAML Status on. Saving with SAML Status off stores the values but does not change the live connection.

User provisioning

Once the domain is Verified and SAML Status is on, users invited to the organization are not sent a password-setup email. Their account is created on first SSO sign-in.
A user who already has a Zenskar password is asked once, on their first SSO sign-in, to link SSO to their account by confirming that password.

Scope

One SAML configuration per organization, applied organization-wide rather than per business entity. The configuration is held against the production organization; sandbox access uses the same configuration.

Permissions

Action	Permission
View the SAML configuration	`can_read_saml`
Generate TXT records and verify the domain	`can_create_saml`
Save the SAML configuration	`can_update_saml`

Keeping SAML running

Certificate rotation. Identity provider signing certificates expire. When the identity provider issues a replacement, paste it into the Certificate field on the SAML tab and save with SAML Status on. Do this before the old certificate expires to avoid an interruption. A sign-in that worked before and now fails with a signature or certificate error usually means the certificate was rotated. Adding and removing access. Access is controlled at the identity provider, through the users and groups assigned to the Zenskar application, or the organizational units the app is turned on for. Removing a user there stops their Zenskar sign-in immediately, with no separate change in Zenskar. Passwords. Zenskar never receives or stores identity provider passwords. Authentication happens entirely at the identity provider, which tells Zenskar only that it succeeded. A user who already had a Zenskar password confirms it once to link their account on first SSO sign-in; after that, sign-in always goes through the identity provider.

Troubleshooting

Symptom	Cause and fix
The identity provider shows an “app not configured for user” or “not assigned” error	The user is not assigned to the Zenskar application at the identity provider. Assign the user or their group.
Clicking the Zenskar tile in the identity provider shows an error page	Expected. Sign-in must start from the Zenskar sign-in page; users who go there directly are unaffected. Hide the app’s tile at the identity provider, and have the team bookmark the Zenskar sign-in page instead.
The user is asked to enter their name on first sign-in	The first-name or last-name attribute is missing, or its name does not match the Attribute Mapping on the SAML tab. Attribute names are case-sensitive.
Signature or certificate error	The certificate on the SAML tab is incomplete or does not match the identity provider’s current signing certificate. Re-copy it in full, including the BEGIN and END lines, and save.
Sign-in worked before and now fails	The identity provider’s signing certificate was rotated. Paste the new certificate into the SAML tab and save.
Sign-in falls back to email and password	The domain is not Verified, or the configuration was last saved with SAML Status off. Check both on the SAML tab.

Getting started

Product modules

Security

Model context protocol (MCP)

Pricing models

Third-party integrations

Zenskar versioning

SAML tab fields

Connection

Identity Provider Configuration

Attribute Mapping

Zenskar SAML Configuration Values

Field validation

Zenskar’s SAML values

Domain verification

The SAML assertion Zenskar expects

Applying changes

User provisioning

Scope

Permissions

Keeping SAML running

Troubleshooting

​SAML tab fields

​Connection

​Identity Provider Configuration

​Attribute Mapping

​Zenskar SAML Configuration Values

​Field validation

​Zenskar’s SAML values

​Domain verification

​The SAML assertion Zenskar expects

​Sign-in behavior

​Applying changes

​User provisioning

​Scope

​Permissions

​Keeping SAML running

​Troubleshooting

SAML tab fields

Connection

Identity Provider Configuration

Attribute Mapping

Zenskar SAML Configuration Values

Field validation

Zenskar’s SAML values

Domain verification

The SAML assertion Zenskar expects

Sign-in behavior

Applying changes

User provisioning

Scope

Permissions

Keeping SAML running

Troubleshooting