ZoneWatcher
Features Integrations Compliance Pricing FAQ Blog
Sign In Register

Single Sign-On (SAML 2.0)

Single sign-on lets your team authenticate to ZoneWatcher through your existing identity provider using SAML 2.0. This guide walks through the benefits, the setup steps for the most common identity providers, and the break-glass API you can use if your IdP goes down.

Why use SSO?

Centralizing authentication through your identity provider reduces password sprawl, makes onboarding and offboarding instant, and gives security teams a single place to enforce policy. SAML 2.0 is the standard protocol for enterprise identity federation and works with virtually every modern IdP.

Instant offboarding
When you deactivate an employee in your IdP, their ZoneWatcher access is gone the next time they try to sign in. No stale accounts to clean up.
No more passwords
Team members sign in with the same credentials they use everywhere else. Password resets, lockouts, and credential reuse stop being your problem.
Centralized MFA & policy
Enforce hardware keys, conditional access, IP restrictions, and session policies in your IdP. ZoneWatcher inherits whatever you configure upstream.
Audit & compliance
A single source of truth for who has access to what — useful evidence for SOC 2, ISO 27001, HIPAA, and PCI DSS audits.
Faster sign-in
Already authenticated to your IdP? Signing into ZoneWatcher is a single click — no password, no second factor, no friction.
Just-in-time provisioning
When a team member signs in via SAML for the first time, their ZoneWatcher account is created automatically. No manual invites required.

Before you begin

You'll need three pieces of information from ZoneWatcher to configure your identity provider, and three pieces of information from your identity provider to configure ZoneWatcher.

From ZoneWatcher (give these to your IdP)

  • ACS URL (Assertion Consumer Service URL) — where the IdP posts the SAML response.
  • SP Entity ID — identifies ZoneWatcher to the IdP. Auto-generated unless you override it.
  • Metadata URL — an XML document many IdPs can import to skip manual entry.

All three are visible on the SSO Settings page once you create a connection.

From your IdP (paste these into ZoneWatcher)

  • IdP Entity ID — uniquely identifies your identity provider.
  • IdP SSO URL — where ZoneWatcher sends users to authenticate.
  • X.509 certificate — the public key ZoneWatcher uses to verify SAML assertions.

Recommended: configure from a metadata URL

Most identity providers expose a metadata URL — typically ending in /metadata or /federationmetadata.xml — that bundles the entity ID, SSO URL, and signing certificate in a single XML document. Pointing ZoneWatcher at this URL is the easiest way to set up a connection and the only way to get free certificate rotation.

When you choose Metadata URL in the SAML connection form, ZoneWatcher fetches the document over HTTPS, parses it, and stores the IdP fields atomically. After that, a daily background job re-fetches the URL — and any time a certificate enters its 30-day expiry window, ZoneWatcher pulls the metadata immediately to pick up rotated certificates with zero manual work.

Manual paste is still supported and existing connections are unaffected. If you can choose, choose metadata URL.

Where to find the metadata URL

  • Google Workspace: Apps → Web and mobile apps → your app → SAML metadata link in the Service provider details panel.
  • Microsoft Entra ID: Enterprise applications → your app → Single sign-on → SAML → App Federation Metadata Url under SAML Certificates.
  • Okta: Applications → your app → Sign On tab → Metadata URL under the SAML signing certificates.
  • JumpCloud: SSO Applications → your app → SSO tab → IdP Metadata download (or use the URL shown).
  • OneLogin: Applications → your app → SSO tab → SAML Metadata download URL.

Refresh status

The SSO Settings page shows when ZoneWatcher last synced from your metadata URL and surfaces an explicit error message if the most recent fetch failed. We keep the last-known-good values in place so a temporary IdP outage doesn't break sign-in. Click Refresh metadata at any time to retry.

Setup by identity provider

The exact steps differ by IdP, but the shape of the work is the same: create a SAML application in your IdP, exchange URLs and a certificate with ZoneWatcher, then test the connection. Pick your provider below.

  1. In the Google Admin console, go to Apps → Web and mobile apps and click Add app → Add custom SAML app.
  2. Name the app "ZoneWatcher", optionally upload a logo, and click Continue.
  3. On the Google Identity Provider details screen, copy the SSO URL, Entity ID, and download the Certificate (or grab the SAML metadata link — recommended; see "Configure from a metadata URL" above).
  4. On the Service provider details screen, paste the ACS URL and Entity ID shown on ZoneWatcher's SSO Settings page after you create the connection. Set Name ID format to EMAIL and Name ID to Basic Information → Primary email.
  5. On the Attribute mapping step, map Basic Information → First name to app attribute firstName and Basic Information → Last name to lastName so display names render correctly.
  6. Click Finish. Back in the app's settings, set User access to ON for everyone (or scope to the OU/group that should have access).
  7. In ZoneWatcher, open SSO Settings → Add SAML Connection. Either paste the SAML metadata URL (recommended), or paste the IdP Entity ID, SSO URL, and certificate from step 3.

Google's identifiers usually look like https://accounts.google.com/o/saml2?idpid=....

  1. In the Microsoft Entra admin center, go to Identity → Applications → Enterprise applications and click New application → Create your own application.
  2. Name the app "ZoneWatcher", choose Integrate any other application you don't find in the gallery, and create it.
  3. Open Single sign-on and select SAML.
  4. Under Basic SAML Configuration, set the Identifier (Entity ID) and Reply URL (ACS URL) to the values shown on ZoneWatcher's SSO Settings page.
  5. Under SAML Certificates, download the Certificate (Base64).
  6. Under Set up ZoneWatcher, copy the Login URL and Microsoft Entra Identifier.
  7. Assign users or groups under Users and groups.
  8. In ZoneWatcher, open SSO Settings → Add SAML Connection. Use the Entra Identifier as the IdP Entity ID, the Login URL as the IdP SSO URL, and upload the Base64 certificate.
  1. In the Okta Admin Console, go to Applications → Applications and click Create App Integration.
  2. Choose SAML 2.0 and click Next. Name the app "ZoneWatcher" and continue.
  3. Under SAML Settings, paste the Single sign-on URL (ZoneWatcher's ACS URL) and Audience URI (SP Entity ID) from ZoneWatcher's SSO Settings page.
  4. Set Name ID format to EmailAddress and Application username to Email.
  5. Click Next, mark this as an internal app, and click Finish.
  6. On the application's Sign On tab, click View SAML setup instructions (or use the Identity Provider metadata link). Copy the Identity Provider Single Sign-On URL, Identity Provider Issuer, and download the X.509 Certificate.
  7. Assign users or groups on the Assignments tab.
  8. In ZoneWatcher, open SSO Settings → Add SAML Connection and paste the values from step 6.
  1. In the JumpCloud Admin Portal, go to SSO Applications and click + Add New Application.
  2. Search for "Custom SAML App" and select Custom SAML App.
  3. On the General Info tab, give the app a display name like "ZoneWatcher".
  4. On the SSO tab, set IdP Entity ID to a stable value (you can leave the default), set SP Entity ID and ACS URL to the values shown on ZoneWatcher's SSO Settings page, and set SAMLSubject NameID to email with SAMLSubject NameID Format set to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
  5. Click Activate. JumpCloud will generate the IdP certificate — download it.
  6. Open the application again and copy the IdP URL (your IdP SSO URL) and the IdP Entity ID.
  7. Assign user groups on the User Groups tab.
  8. In ZoneWatcher, open SSO Settings → Add SAML Connection and paste the values from steps 5 and 6.
  1. In the OneLogin Admin portal, go to Applications → Applications and click Add App.
  2. Search for "SAML Custom Connector (Advanced)" and select it.
  3. Name the connector "ZoneWatcher" and save.
  4. On the Configuration tab, set Audience (EntityID) and ACS (Consumer) URL to the values shown on ZoneWatcher's SSO Settings page. Set SAML nameID format to Email.
  5. On the SSO tab, set SAML Signature Algorithm to SHA-256. Copy the Issuer URL (IdP Entity ID), SAML 2.0 Endpoint (HTTP) (IdP SSO URL), and download the X.509 Certificate.
  6. Assign the app to users or roles on the Users tab or via OneLogin's role mapping.
  7. In ZoneWatcher, open SSO Settings → Add SAML Connection and paste the values from step 5.

ZoneWatcher works with any SAML 2.0 compliant identity provider. The general flow:

  1. In ZoneWatcher, open SSO Settings and start adding a SAML Connection so you have the ACS URL and SP Entity ID handy. (You can save the connection with placeholder IdP values and edit them after.)
  2. In your IdP, create a new SAML 2.0 service provider / application using ZoneWatcher's ACS URL as the Assertion Consumer Service / Reply URL and the SP Entity ID as the Audience / Entity ID.
  3. Configure the IdP to release the user's email address as the NameID, in the urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress format. ZoneWatcher does not require any other attributes.
  4. From the IdP, retrieve the Entity ID, the SSO URL (HTTP-Redirect or HTTP-POST binding), and the public X.509 signing certificate.
  5. Back in ZoneWatcher, paste those three values into the SAML Connection and save.

If your IdP supports SP metadata import, the Metadata URL shown on ZoneWatcher's SSO Settings page contains everything it needs.

Attribute mapping

ZoneWatcher needs the user's email and reads name and avatar fields when present. Most identity providers send these as standard SAML claim URIs out of the box — you usually don't need to configure anything explicitly. But if you want display names to look right ("Jane Doe" instead of "jane.doe"), make sure your IdP releases first name and last name attributes.

ZoneWatcher field Required? Recognized SAML claim URIs & keys
email Required

NameID (preferred — set the format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) plus any of:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • urn:oid:0.9.2342.19200300.100.1.3
  • Plain keys: email, mail, emailAddress
first name Recommended
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • urn:oid:2.5.4.42
  • Plain keys: firstName, first_name, givenName
last name Recommended
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  • urn:oid:2.5.4.4
  • Plain keys: lastName, last_name, surname, familyName
display name Optional fallback

Used if first/last names aren't available.

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • urn:oid:2.16.840.1.113730.3.1.241
  • Plain keys: name, displayName, cn
avatar URL Optional
  • http://schemas.microsoft.com/identity/claims/photo
  • urn:oid:0.9.2342.19200300.100.1.60
  • Plain keys: picture, photo, avatar

ZoneWatcher also honours the FriendlyName attribute on a SAML Attribute element, so an attribute named urn:custom:givenName with friendly name firstName will work without extra configuration.

Where to configure attribute mapping in your IdP

  • Okta: Application → General → SAML Settings → Attribute Statements.
  • Microsoft Entra ID: Enterprise application → Single sign-on → Attributes & Claims.
  • Google Workspace: Custom SAML app → Attribute mapping step.
  • JumpCloud: Application → SSO → Attributes.
  • OneLogin: Application → Parameters.

Test the connection

On the SSO Settings page, the Login URL link opens your IdP-initiated sign-in flow in a new tab. Use it to verify the round trip works before you turn on enforcement. If you see an error, double-check the certificate (no extra whitespace), the IdP SSO URL (must be the SAML endpoint, not the IdP's homepage), and the Name ID format (must be email).

Claim your domain

Domain claiming associates an email domain (like acme.com) with your team. Once claimed, anyone who lands on the ZoneWatcher login page and enters an email matching that domain is automatically routed to your SAML flow — no need to remember a tenant-specific URL.

Set this on the SSO Settings page under Domain Claiming. Each domain can be claimed by exactly one team.

Enforce SSO

With at least one active SAML connection, the team owner can flip SSO Enforcement on. Once enforced:

  • All team members must authenticate through your IdP — password and social logins are blocked.
  • Existing sessions that didn't authenticate via SAML are signed out.
  • The two-factor requirement is skipped for SAML-authenticated users (you'll enforce 2FA in your IdP).
  • Super admins remain exempt as a safety net.

If you delete or disable your last active SAML connection, ZoneWatcher automatically turns enforcement off so you don't lock yourself out.

Account linking for existing users

When a SAML assertion arrives for a brand-new email, ZoneWatcher creates the account on the spot. When it arrives for someone who already has a ZoneWatcher account but isn't a member of your team, the default behaviour is to reject the login and ask them to be invited the normal way — that's the safest default if your IdP is misconfigured.

If you'd rather let those users self-serve, flip the Auto-join existing users toggle on the connection. With it enabled, ZoneWatcher emails the existing account a one-time confirmation link instead of rejecting the login. Clicking the link, while signed into their existing ZoneWatcher account, both:

  • Records the SAML identity (issuer + NameID) against their account so future SSO logins find them directly.
  • Adds them to your team as a member.

Some details worth knowing:

  • The link expires in 24 hours. If it expires, signing in via SSO again will dispatch a fresh link and void the old one.
  • Each new link voids any prior unused link for the same (user, team) pair, so a stolen stale token can't be replayed.
  • If the user clicks the link without being signed in, ZoneWatcher prompts them to sign in to their existing account first, then completes the bind.
  • A different signed-in user clicking the link is rejected — the email and the authenticated user must match.
  • If they're already a member of the team (e.g. invited separately in the meantime), the bind is recorded but their existing role is preserved.
  • Once linked, whether their password remains usable is governed by the team's SSO Enforcement setting, not the link itself.

The toggle is off by default to avoid sweeping unrelated users into a team if your IdP releases the wrong attribute set during testing.

Certificate management

SAML connections sign every assertion with an X.509 certificate that has a hard expiry. When the cert expires, SSO breaks. ZoneWatcher tracks the certificate's notAfter date and surfaces it on the SSO Settings page.

Health badges

  • No badge — certificate is more than 30 days from expiry.
  • Certificate expires X — within the 30-day warning window.
  • Certificate expired — already past notAfter; the connection is auto-disabled.

Email warnings

The team owner and every admin-role member get an email at 30, 14, 7, and 1 days before expiry — once per threshold, not once per day. If the certificate is rotated (because you re-uploaded one or because the metadata URL refresh picked up a new one), the warning ladder resets.

Auto-refresh from metadata URL

For connections configured with a metadata URL, ZoneWatcher pulls the metadata immediately whenever a certificate enters the 30-day window — separately from the daily refresh cron — so a rotated certificate is picked up without any intervention.

What happens at expiry

When a certificate actually expires, ZoneWatcher disables the connection. If it was the last enabled connection on the team, SSO enforcement is automatically lifted so password login keeps working. The owner and admins get an email explaining what happened and how to remediate (re-upload the certificate, or refresh the metadata URL).

Security & compliance

The SAML implementation is designed to fail closed. Specific guarantees a procurement review is likely to ask about:

  • Signature algorithms. SHA-1 family signatures (RSA-SHA1, DSA-SHA1, HMAC-SHA1) are explicitly rejected before verification. Production assertions must be signed with RSA-SHA256 or stronger.
  • Audience restriction. Every assertion's <AudienceRestriction> is checked against this team's SP entity ID. A valid assertion intended for a different service provider is rejected even if the signature passes.
  • Replay protection. Assertion IDs are cached on first use; replays of the same assertion are rejected for the lifetime of the cache entry.
  • Strict assertion validation. The SAML Version, IssueInstant, ID, and Issuer fields are required and validated.
  • Required NameID format. The NameID must be the user's email — opaque or transient identifiers are accepted only when an explicit email attribute is also present.
  • Encryption in transit. Metadata URL imports are HTTPS-only; HTTP URLs are rejected at submit time.
  • Certificate at rest. The IdP signing certificate is encrypted in the database via Laravel's encrypted cast.
  • API tokens unaffected by SSO. Personal API tokens issued in Account Settings continue to work even when SSO enforcement is on, so automation and the break-glass endpoint keep functioning during an IdP outage.
  • Audit-friendly break-glass. The enforcement-disable endpoint requires the team owner's personal API token, scopes to a specific team ID, and is logged as a normal API request.

Break-glass API: recovering from an IdP outage

If your identity provider goes down while SSO is enforced, the entire team is locked out of the app UI. The break-glass endpoint lets the team owner disable enforcement out-of-band using a personal API token, restoring password and social logins until your IdP is back.

Endpoint

DELETE /api/sso/enforcement/{team_id}

Example

# Replace team_abc123 with your team ID
curl -X DELETE https://app.zonewatcher.com/api/sso/enforcement/team_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Requirements

  • The token must belong to the team owner. Admins and members get a 403.
  • The URL must include your team ID. If you own multiple teams, this avoids ambiguity — the curl example on the SSO Settings page is pre-filled with the current team's ID, so the easiest path is to copy it from there.
  • Generate a personal API token in your Account Settings. Store it somewhere your IdP outage won't take with it — a password manager that doesn't depend on SSO, or an offline note kept by the team owner.

Response

{
  "message": "SSO enforcement has been disabled.",
  "force_sso": false
}

Plan for break-glass before you need it

Generate the API token now, store it securely with the team owner, and document the curl command in your runbook. The first time you should run this command is during a drill, not during an actual outage.

Common pitfalls

Certificate parse errors
When pasting the X.509 certificate, the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers are stripped automatically — but extra whitespace around the body can still cause failures. Uploading the file directly is the most reliable option.
Wrong NameID format
ZoneWatcher matches users by email address. If your IdP sends a UUID, immutable ID, or username as the NameID, sign-in will succeed but a fresh user account will be created on every login. Make sure NameID is the user's email.
Domain claim conflict
A domain can only be claimed by one team. If you see a "domain already claimed" error, another team has already taken it — contact support if it should be yours.
Locked out without break-glass
If the team owner doesn't have a personal API token saved, an IdP outage means waiting for support to disable enforcement manually. Generate the token before you need it.
Certificate rotated upstream but not downstream
If your connection is configured manually (no metadata URL), rotating the IdP signing certificate breaks SSO until you paste the new one into ZoneWatcher. Switch the connection to a metadata URL to make rotations automatic.

Ready to set up SSO?

Sign in to ZoneWatcher and open Settings → SSO Settings in your team to add a SAML connection, claim your domain, and turn on enforcement. SSO is included on plans that support it — check your billing page for details.

Don't have an account yet? Start your free trial.

Never miss a DNS change again.
Start monitoring in minutes.

Start Trial Learn more