> ## Documentation Index > Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Reference > SAML tab fields, validation rules, domain verification, and the assertion Zenskar expects. 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](#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/-/endpoint`, where `` 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.` | | Value | `zenskar-verify=`, where `` 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 behavior 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. |