> ## 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.
# SAML authentication with Google Workspace
Zenskar supports single sign-on (SSO) through SAML 2.0, letting an organization authenticate users through its existing identity provider. This guide sets up SAML in Zenskar using **Google Workspace** (or Cloud Identity) as the identity provider.
If terms like identity provider (IdP) and service provider (SP) are unfamiliar, start with the Concepts page.
Field-level detail, validation rules, and the assertion Zenskar expects. Keep it open while you work through the steps.
This guide is for administrators. You need admin access to both Google Workspace and Zenskar: a Google Workspace super administrator account, and a Zenskar role with SAML permissions. If your organization does not use Google Workspace yet, set it up and add your users there first. Adding the Zenskar application does not change your existing Google Workspace setup, and your users keep the credentials they already use.
Sign-in must start from the Zenskar sign-in page. Launching Zenskar from the Google app launcher does not complete sign-in.
Zenskar does not control the Google Admin console, and Google may rename or move fields at any time. Each Google Workspace label in this guide is paired with the SAML 2.0 concept it maps to, which does not change, so a rename does not break the mapping. The labels were accurate on 2 September 2026; if one no longer matches what you see, match on the concept and use [Google's current guide to setting up your own custom SAML app](https://support.google.com/a/answer/6087519) to find the field.
***
## Step 1: Verify your domain
1. Click the account menu at the bottom of the sidebar, and select **Settings**.
2. Open the **SAML** tab.
3. In the **Connection** section, enter a **Name** for this configuration and the **Domain** to verify, for example `acme.com`. Enter the bare domain, with no `https://` prefix and no path.
4. Click **GET TXT RECORDS**.
5. Add the resulting TXT record to the domain's DNS.
6. Click **VERIFY DOMAIN** once the record has propagated. The domain's status changes from Pending to Verified.
7. Under **Identity Provider**, select **Google Workspace** from the dropdown. This is the default selection.
If **VERIFY DOMAIN** reports a failure, the TXT record may not have propagated yet. DNS changes can take from a few minutes to 48 hours; wait and try again.
## Step 2: Set up the application in Google Workspace
Create a custom SAML app for Zenskar. On the **Google Identity Provider details** screen, download the certificate file and copy the SSO URL and Entity ID; you enter these in Zenskar in Step 3. Then turn the app on for the users or organizational units who should be able to sign in to Zenskar.
#### Service provider values
From the **Zenskar SAML Configuration Values** section on the SAML tab, enter these in Google Workspace:
| SAML 2.0 concept | Google Workspace field | Zenskar field |
| --------------------------------------- | ------------------------------------ | ------------- |
| SP Assertion Consumer Service (ACS) URL | ACS URL (Service provider details) | ACS URL |
| SP entity ID / audience | Entity ID (Service provider details) | Entity ID |
The ACS URL appears once Google Workspace is selected on the SAML tab in Step 1. Copy it and the Entity ID exactly as shown.
#### NameID
| SAML 2.0 concept | Google Workspace field | Value |
| ---------------- | ---------------------- | ------------- |
| NameID format | Name ID format | `EMAIL` |
| NameID value | Name ID | Primary email |
#### Attribute statements
| SAML 2.0 concept | Google app attribute | Mapped from | Zenskar field (Step 3) |
| -------------------- | -------------------- | ------------- | ------------------------- |
| Email attribute | `email` | Primary email | User ID and Email address |
| Given name attribute | `firstName` | First name | First name |
| Surname attribute | `lastName` | Last name | Last name |
Attribute names are case-sensitive and must contain no spaces. If the first or last name attribute is missing, Zenskar asks the user to enter their name on first sign-in.
Leave anything else at its default.
## Step 3: Finish in Zenskar
On the **SAML** tab, in the **Identity Provider Configuration** section, enter these values from Google Workspace:
| SAML 2.0 concept | Google Workspace field | In the downloaded IdP metadata | Zenskar field |
| ------------------------------- | -------------------------------------------- | ------------------------------ | --------------------------- |
| IdP entity ID / issuer | Entity ID (Google Identity Provider details) | `entityID` attribute | Identity Provider Entity ID |
| IdP single sign-on endpoint | SSO URL | `` | Single Sign-On Service URL |
| IdP signing certificate (X.509) | Certificate | `` | Certificate |
Zenskar needs the certificate as a PEM block with its `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. The `` value in the metadata XML has no such lines and will fail the check: use the certificate file downloaded in Step 2, or wrap the Base64 in those lines before pasting.
Then set the four **Attribute Mapping** fields to the attribute names from Step 2.
Turn on **SAML Status** and click **Save Configuration**. Zenskar checks the form first: with SAML Status on, the Name, Domain, both Identity Provider Configuration values, the Certificate, and all four attribute mappings are required, and the single sign-on URL must use `https`. See [Field validation](/docs/20260301/security/saml-authentication/reference#field-validation) for the certificate format and the other checks.
**Good to know**
* A user who already has a Zenskar password confirms it once, on their first SSO sign-in, to link their account. Every sign-in after that goes through Google.
* Once the domain is verified and SAML Status is on, invited users no longer receive a password-setup email; their account is created on first SSO sign-in.
* To change an Identity Provider Configuration value later, edit the field with **SAML Status** on and click **Save Configuration** again. A save made while SAML Status is off is stored but does not update the live connection.
## Step 4: Test
1. Test in a private or incognito window: go to the Zenskar sign-in page, enter the work email address of a user the app is turned on for, and continue. The sign-in should route to Google and return to the Zenskar dashboard.
2. Test with a second user before announcing it to the team. This confirms the app is on for the right organizational units, not just one account.
If sign-in fails with a Google `403 app_not_configured_for_user` error right after turning the app on, wait: app access can take up to 24 hours to propagate, though it is usually a few minutes.
## Troubleshooting and upkeep
Common sign-in failures and what each one means.
Certificate rotation, adding and removing access, and passwords.
Reach out to [help@zenskar.com](mailto:help@zenskar.com) with questions while going through setup.