SSO / authentication integration
Configure single sign-on (SSO) so Zenoti admin-portal users authenticate through your organization's identity provider (IdP) instead of a separate Zenoti password. This article covers SAML 2.0 setup end-to-end β the Zenoti (service provider) configuration, the IdP-side application and attribute mapping, login and logout flows, failure handling, and break-glass recovery.
On this page
- Supported deployment model
- Before you begin
- External-system prerequisites
- Network requirements
- Configure SSO at the organization level
- Configure your identity provider
- Test SSO and roll out
- Break-glass: regain access if SSO fails
- Rotate or renew the IdP signing certificate
- Disable or offboard SSO
- Failure paths
- Tips
- Related articles
Supported deployment model
Zenoti supports SAML 2.0 for admin-portal SSO. OAuth/OIDC flows are used internally by specific integrations (for example, the SSO redirect flow that wraps the login page), but tenant-level workforce SSO is configured through SAML.
| Item | Value |
|---|---|
| Protocol | SAML 2.0 (IdP-initiated or SP-initiated) |
| Binding | HTTP-POST for assertions, HTTP-Redirect for AuthnRequest |
| Assertion signing | Required (SHA-256 recommended) |
| Encryption | Optional (configure on the IdP if required by your security policy) |
| Session scope | Zenoti admin portal. MyZen, Webstore, and the consumer mobile app use separate authentication flows. |
If your IdP only issues OIDC tokens, engage Zenoti Support before planning the rollout β Zenoti does not auto-provision OIDC-only tenants.
Before you begin
Permission: You need organization administrator access to configure SSO at the tenant level. IdP-side changes require an administrator on the identity provider (Azure AD / Entra ID, Okta, Google Workspace, Ping, ADFS, or any SAML 2.0 provider).
- Plan a maintenance window. Toggling SSO modes while users are signed in can force re-authentication.
- Identify a break-glass administrator β at least one Zenoti admin who will continue to log in with a local Zenoti password if SSO breaks. Do not enable strict SSO-only mode for this account.
- Confirm that all intended SSO users exist in both Zenoti (as employees with email addresses) and the IdP, using the same email address as the join key.
- SAML is configured at organization scope under Configuration > Integrations > Integration settings; there is no separate SSO page under Security.
External-system prerequisites
SSO requires configuration on your IdP side, not only in Zenoti. These steps are the customer's responsibility and vary by IdP; consult the IdP's own documentation for exact menu paths.
- SAML application (IdP side). Create a new SAML 2.0 application for Zenoti in your IdP admin console (for example, Azure AD "Enterprise applications > New application", Okta "Applications > Create app integration > SAML 2.0", Google Workspace "Web and mobile apps > Add custom SAML app").
- Signing certificate (IdP side). Ensure the SAML app has a valid X.509 signing certificate. Note the expiry date and set a calendar reminder to rotate before expiry β expired certificates cause total SSO outage.
- User assignment (IdP side). Assign the Zenoti SAML app to the IdP groups or users who should be able to sign in. Users not assigned in the IdP cannot authenticate even if they exist in Zenoti.
- Attribute mapping (IdP side). Configure the IdP to send at minimum the user's email, first name, and last name in the SAML assertion.
- Service account for break-glass (Zenoti side). Maintain at least one non-SSO Zenoti admin account. This account must have a strong local password and MFA where available.
If your organization uses Zenoti University (Northpass), also see Configure Zenoti University β the learning portal has its own SSO enablement that can reuse the same IdP.
Network requirements
SAML SSO is a browser-redirect flow, so the user's browser is what talks to the IdP β Zenoti does not open a back-channel connection to the IdP. Ensure the following endpoints are reachable from your users' network:
| Direction | Endpoint | Port | Purpose |
|---|---|---|---|
| Browser β IdP | Your IdP's SSO URL (for example, https://login.microsoftonline.com/...) |
443 (HTTPS) | SAML AuthnRequest and assertion flow |
| Browser β Zenoti | Your Zenoti tenant URL (https://<org>.zenoti.com) |
443 (HTTPS) | AssertionConsumerService (ACS) POST from the IdP |
| Browser β IdP metadata URL (optional) | Your IdP's metadata endpoint | 443 (HTTPS) | Only required if you choose to fetch metadata dynamically; the common pattern is to upload metadata once |
HTTP is not supported. If your organization uses a strict egress proxy, whitelist both the Zenoti tenant URL and the IdP URLs for browsers on corporate networks.
Configure SSO at the organization level
SAML is an accordion on the Integration settings page. It is available at organization scope only.
Navigate to Configuration > Integrations > Integration settings.
Expand SAML.
Fill in the rows below. All values come from the IdP administrator or the IdP metadata XML.
Setting Type What to enter Enable SAML Checkbox Turns SAML sign-in on for the organization. Leave it clear until the IdP side is configured and tested. Identity Provider Single Sign-On URL Text The IdP's single sign-on endpoint that the browser is redirected to. X.509 Certificate Text area The IdP's public signing certificate, pasted as text. User Identifier Text The SAML attribute that carries the user's identity. Zenoti matches it against the employee's email address. Identity Provider Issuer Text The IdP's unique SAML identifier (its entity ID). Provider Name Text Friendly name shown on the Zenoti sign-in page, for example "Contoso SSO". Allow Direct Login Dropdown Which users may still sign in with a Zenoti password: None, Web, Mobile, or All. Keep at least the break-glass administrator's channel open. Enable SLO Checkbox Turns on SAML single logout. When selected, the single logout URL and signature rows appear below it. Select Save at the bottom of the page.
Zenoti does not publish a service-provider metadata file on this page. Use your tenant URL as the assertion consumer endpoint when you configure the IdP; if your IdP requires an explicit entity ID or ACS URL, ask Zenoti Support for the values for your tenant.
Configure your identity provider
Configure the Zenoti application inside the IdP.
- In the IdP's SAML application for Zenoti, set:
- Audience / SP Entity ID and ACS URL / Reply URL / Single sign-on URL to the values for your Zenoti tenant.
- The Name ID or attribute that carries the user's email address, matching User Identifier in Zenoti.
- Map the IdP user attributes so the assertion carries the user's email address in the attribute named by User Identifier.
- Assign users or groups to the application.
- Save in the IdP.
The IdP vendor's documentation is the authoritative source for the exact menu paths β these change across IdP versions.
Test SSO and roll out
- Keep your break-glass admin logged in on a separate browser so you can roll back if anything breaks.
- In Zenoti, select Enable SAML and save, keeping Allow Direct Login at All so password sign-in still works during the test.
- Using a second browser profile, open your Zenoti tenant URL.
- Choose the SSO sign-in option; it carries the Provider Name you configured.
- The browser redirects to the IdP. Authenticate using a test user who is assigned to the IdP app.
- After authenticating, you are redirected back to Zenoti and signed in.
- Verify:
- The user matches the expected Zenoti employee record.
- The user's permissions are as expected (SSO does not change role assignments β it only authenticates).
- Logout from Zenoti ends the session.
- When satisfied, tighten Allow Direct Login to the channels you still want to allow and communicate the change to users.
Phase the rollout by center or by user group if your IdP supports app-assignment scoping β this is safer than flipping the entire tenant at once.
Break-glass: regain access if SSO fails
If SSO stops working (for example, the IdP certificate expires or the IdP is unreachable) and every admin account is SSO-only, the organization is locked out. Prevent this:
- Maintain at least one Zenoti admin account that can sign in with a local Zenoti password, and keep Allow Direct Login open for that channel. Setting it to None removes every password sign-in path.
- Store the break-glass credentials in your organization's secrets vault, with access restricted to senior administrators.
- Test the break-glass login quarterly β the account must remain active and its password known.
To recover using the break-glass admin:
- Sign in with the break-glass administrator's Zenoti password. This works only if Allow Direct Login was left at Web or All for the channel you use.
- Navigate to Configuration > Integrations > Integration settings, expand SAML, and clear Enable SAML or correct the broken value.
- Select Save.
- Re-enable SAML once the IdP issue is fixed.
If no break-glass admin exists and every user is locked out, open a Zenoti Support ticket with an identity-proof request. Recovery requires organization-level verification and takes longer than a planned rotation.
Rotate or renew the IdP signing certificate
Certificates expire. An expired signing certificate causes every SAML assertion to fail validation, which presents as a total SSO outage.
- Generate or obtain the new certificate in your IdP admin console before the old one expires.
- If your IdP supports dual certificates (both old and new valid during a grace window), enable both.
- In Configuration > Integrations > Integration settings > SAML, paste the new certificate into X.509 Certificate.
- Save.
- Sign in using a test account.
- After confirming the new certificate works, retire the old certificate on the IdP.
Set a calendar reminder at least 30 days before any certificate expiry. Zenoti does not proactively notify users of impending expiry.
Disable or offboard SSO
- Sign in with the break-glass admin.
- In Configuration > Integrations > Integration settings, expand SAML and clear Enable SAML.
- Select Save.
- Communicate to users that they will sign in with Zenoti credentials. Users who never set a Zenoti password need a password reset. Go to Employee > Employee, open the employee record, and select Reset Password.
- (Optional) Clear the SAML rows if you do not plan to reactivate.
Failure paths
SAML SSO has several well-known failure modes. The table lists each mode with the user-visible symptom and the resolution path.
| Failure mode | User-visible symptom | Resolution |
|---|---|---|
| IdP unreachable | Browser shows IdP error page or times out during redirect to the IdP. | Check IdP status page. Confirm DNS and browser egress to the IdP URL. Use break-glass admin if the outage is prolonged. |
| Expired IdP signing certificate | Zenoti shows "Invalid SAML signature" or a generic sign-in failure after the IdP round-trip. | Rotate the certificate β see Rotate or renew the IdP signing certificate. |
| Clock skew between IdP and Zenoti | Assertion rejected as "NotBefore in the future" or "NotOnOrAfter in the past". | Ensure the IdP time source is synced with NTP. SAML allows a small skew (typically 5 minutes) but large drift fails. |
| User not assigned in IdP | IdP denies the login before returning to Zenoti. | Assign the user to the Zenoti app in the IdP. |
| User exists in IdP but not in Zenoti | Zenoti shows "User not provisioned" (or similar) after the IdP round-trip. | Create the employee record in Zenoti with the same email that the IdP sends, then retry. |
| Attribute mapping mismatch | Zenoti receives the assertion but cannot read the user's email. | Confirm that User Identifier names the attribute the IdP actually sends. Use the IdP's SAML trace/debug tool. |
| Wrong reply URL in IdP | IdP posts the assertion to the wrong endpoint and the browser shows a 404 or a mismatched-tenant error. | Correct the reply URL in the IdP to your Zenoti tenant's endpoint (confirm the exact value with Zenoti Support). |
| SLO (single logout) misconfigured | Users are logged out of the IdP but remain signed in to Zenoti, or vice versa. | Either align the single logout URL on both sides, or clear Enable SLO and document that users close the browser after logout. |
Generic "SSO is broken β please retry" messaging is not a substitute for this table. When a user reports an SSO failure, collect the IdP trace (most IdPs expose a SAML-tracer feature) and match against the symptoms above.
Tips
- Test SSO thoroughly across multiple user accounts and roles before enforcing it organization-wide.
- Set a calendar reminder 30 days before every IdP certificate expiry.
- Do not bypass SSO once it is the primary auth mode; the break-glass admin is for outages, not day-to-day convenience.
- Enforce MFA at the IdP, not at Zenoti, when SSO is enabled. Zenoti honours whatever assurance the IdP asserts.
- Keep SSO login events visible: most IdPs offer sign-in logs that are richer than Zenoti's own login audit.