SSO, SAML and SCIM

Before you start

• Difficulty: Medium
• Time: 20-30 minutes
• You need: The workspace owner's account
• You need: Admin access to Okta, Microsoft Entra ID, Google Workspace or another identity provider
• You need: Access to your domain's DNS

Steps

1. Prove your domain

   Settings → Single sign-on shows a TXT record: _zchat-verification.{your domain} with the value zchat-verification={token}. Add it to your DNS and choose Check DNS now. A verified domain unlocks just-in-time provisioning and SCIM creating new accounts.

2. Set up SAML 2.0

   Give your identity provider the values shown on the page: the SP entity ID, the ACS URL (HTTP-POST) and the SP metadata, with the email address as Name ID. Then give ZChat the IdP metadata URL, paste its metadata XML, or enter its entity ID, sign-in URL and certificate.

   SP entity ID:  https://app.zchat.com/saml/{workspaceId}
   ACS URL:       https://app.zchat.com/saml/{workspaceId}/acs
   SP metadata:   https://app.zchat.com/saml/{workspaceId}/metadata

3. Or use OpenID Connect

   Any OpenID Connect provider works, including Okta, Entra ID and Google Workspace. Members sign in with Sign in with SSO by entering their work email; the domain picks the workspace.

4. Provision with SCIM

   Create a SCIM token (shown once; up to five active) and give your identity provider the base URL with the token as a Bearer header. Okta and Entra ID create, update and deactivate members; send a roles value of Admin or Agent to set roles.

   Base URL:       https://api.zchat.com/scim/v2
   Authorization:  Bearer zscim_...

5. Require SSO

   Require single sign-on refuses password sign-in for members at your domain. An owner with two-factor enabled can still sign in with password and authenticator code, so a broken identity provider cannot lock the workspace out.

Plans

• OpenID Connect SSO: OpenID Connect SSO is on every plan.
• SAML SSO: SAML SSO is on paid plans with an active subscription. If the plan lapses, existing SAML sign-in keeps working and the setup stays editable; turning SAML on for the first time pauses.
• SCIM: SCIM provisioning is on paid plans with an active subscription. After a lapse SCIM can still read, update and deactivate members, but not create or reactivate them, and no new tokens can be made.
• Just-in-time provisioning: Paid plans with a verified domain. A new person at the domain who passes the identity provider joins with the default role (Agent or Admin, never Owner).

Good to know

• Assertions must not be encrypted, and AuthnRequests are not signed. Single logout is not supported.
• Google Workspace has no SCIM for custom SAML apps: use just-in-time provisioning, and remove leavers in ZChat or by suspending them in Google.
• SCIM Groups, Bulk, ETags and sorting are not supported; roles travel on the roles attribute.
• Sign-ins, rejected responses, provisioning and setting changes are written to the audit log.