Outcome
By the end of this lesson, you will be able to get SAML set up for an enterprise IdP with ZopDev, send the right claims, and identify the most common SAML setup mistakes before they hit production.
| Prerequisites | M4.2.L1: Pick your SSO |
| Time | 10 minutes |
1. Concept
SAML in ZopNight is configured per email domain. A user signing in with jane@example.com is matched against the SAML config whose domain field equals example.com, then redirected to that IdP for authentication. The IdP returns a signed SAML assertion; ZopNight validates the signature, extracts user attributes, and creates a session.
The per-domain approach has two benefits. First, a parent org with multiple email domains (after an acquisition, for example) can route each domain to its own IdP without forcing consolidation. Second, the configuration is bounded, one record per domain, not one per user.
There is no SAML settings page in your ZopNight org. ZopDev staff create and change each per-domain record on an internal admin page. Your job is to prepare the IdP side, send ZopDev the values, and test sign-in once the record exists.
A ZopNight SAML config
customer_name: Example Coemail_domain: example.comtenant_id: <your Azure AD tenant ID>metadata_url: https://login.microsoftonline.com/.../federationmetadata.xmlcert_thumbprint: ABCDEF123456...active: trueThat is the whole record. The form is built around Azure AD (it asks for a tenant ID), so if your IdP is something else, confirm support with ZopDev before you start.
Setup flow
Both sides need to know about each other, but only one side is yours to configure.
STEP 1: In your IdP - Create a SAML 2.0 application - Use the ACS URL and Entity ID that ZopDev gives you - Send the email claim (required) and name (recommended) - Note the metadata URL and the signing certificate's thumbprint
STEP 2: Ask ZopDev to set up SAML for your email domain - Send: email domain, Azure AD tenant ID, IdP metadata URL, certificate thumbprint - ZopDev creates the per-domain record and keeps it inactive until you have tested
STEP 3: Test sign-in - One admin clicks "Continue with SSO" on the login page and enters the email domain - Confirm they land in ZopNight with the right email and name - Tell ZopDev the test passed so the record is switched to active
STEP 4: Roll out - Communicate the change to users - Keep one admin able to sign in another way in case the IdP has an outageMulti-domain setup
Orgs with multiple email domains get one SAML record per domain. Each can point to a different IdP tenant if needed.
EXAMPLE: Parent Co after acquiring AcmeCo:
example.com → Azure AD tenant A (Parent Co's IdP) acme.com → Azure AD tenant B (acquired company's IdP)
Each domain has its own config. Users sign in based on their emaildomain. No cross-domain leakage; the lookup is exact-match.Which IdPs fit
IDP FIT WITH THE CONFIG RECORD──────────────────────────────────────────────────────────────────────Azure AD (Entra ID) Direct fit: the record asks for a tenant ID, metadata URL, thumbprintOkta, OneLogin, other SAML 2.0 Confirm with ZopDev before you startGoogle Workspace Google sign-in is usually simplerThe config record is shaped around Azure AD. For any other IdP, raise it with ZopDev at the start rather than after the IdP app is built.
Attribute mappings
The IdP sends user attributes as SAML claims. ZopNight needs the email claim and uses name when present.
ZOPNIGHT FIELD MUST COME FROM EXAMPLE AZURE AD CLAIM──────────────────────────────────────────────────────────────────user.email IdP claim (required) user.mailuser.name IdP claim (recommended) user.displaynameGroup claims do not drive anything in ZopNight. Roles and team membership are managed in ZopNight itself: members and their roles in Settings → Organization, team membership on the Teams page. Plan that step into the rollout, or new SSO users arrive with no team context.
Common configuration mistakes
After years of customer onboardings, the mistakes cluster. The quoted symptoms are typical wording from the identity provider or sign-in service, not guaranteed; ZopNight does not produce them itself.
MISTAKE SYMPTOM FIX──────────────────────────────────────────────────────────────────────Cert mismatch "Invalid signature" on Re-upload IdP cert assertion from metadata URL
Clock skew Timestamp validation fails Sync system clocks ("Assertion expired" soon via NTP after issue)
Missing email attribute User not created post-login Add email mapping in IdP's attribute config
Cert expiry Suddenly fails one day, all Renew at the IdP and users get "Invalid signature" send ZopDev the new thumbprint
Wrong ACS URL IdP refuses to send the Match exactly: case- assertion (or sends to wrong sensitive, including place) trailing path segments
Wrong Entity ID / Audience "Audience does not match" Match exactly between IdP and ZopNight config
Multiple bindings (HTTP-POST Some browsers fail; others Stick to HTTP-POST+ HTTP-Redirect) work binding for ACS; HTTP-Redirect for SSOThe cert-expiry mistake is the most painful because it manifests as a sudden outage. ZopNight does not warn you about expiry: the record holds only a thumbprint, not a date. Put the IdP signing cert’s renewal date in your own calendar 90 days ahead, and send ZopDev the new thumbprint when you rotate.
How ZopNight uses it
The SAML config is not stored in the ZopNight application or checked by its gateway. ZopNight does not validate SAML assertions; its external auth service holds the config and does the validation, and the gateway only forwards sign-in traffic to it. How strictly that service checks signatures, timestamps and audience is its own behaviour, not something ZopNight documents or controls.
When sign-in fails, ZopNight’s login page shows a short, generic message, for example “Sign-in failed. SAML response was missing.” or “Sign-in failed due to an unexpected error.” The specific reason (a signature or audience problem, say) is usually found in the IdP’s sign-in logs, in the IdP’s or sign-in service’s own wording.
2. Demo
A first-time SAML setup for example.com with Azure AD:
DAY 1 IdP admin creates the SAML app in Azure AD, using the ACS URL and Entity ID from ZopDev; sends email and name claimsDAY 1 Admin emails ZopDev: domain example.com, tenant ID, metadata URL, cert thumbprintDAY 2 ZopDev confirms the per-domain record is in place (inactive)DAY 2 Admin clicks "Continue with SSO", enters example.com → redirected to Azure AD as jane@example.com → back into ZopNight → email and name correctDAY 2 Admin tells ZopDev the test passed; record set to activeDAY 2 Admin adds the first users' roles in Settings → Organization and their teams on the Teams pageDAY 3 Team notified: "SAML SSO is live"
ELAPSED: ~30 minutes of your own work; the rest is the round trip with ZopDev3. Hands-on (6 min)
If you already have SAML configured, audit it:
CURRENT SAML CONFIG (your org):
Domain: __________IdP: __________Cert expiry: __________ days from now (read it in your IdP) (if <90 days, schedule renewal and plan to send ZopDev the new thumbprint)
Claims sent: email: mapped to __________ name: mapped to __________
ACS URL: __________ (matches what ZopDev gave you?)Entity ID: __________
Has the configuration been tested in the last 90 days? Yes / No (If no, run a test sign-in to confirm still works)If you do not have SAML configured yet, sketch the values you would use given your IdP choice (from L1).
Why this part is not in the console or MCP. SAML is set up by ZopDev, not from your org’s console or an assistant, by design: the setup exchanges signing certificates and identity-provider metadata between your IdP admin and ZopDev.
Once SSO is wired, an assistant can tell you who is in the org and what role they hold. It can also add, rename or remove members (add_org_member, update_org_member, remove_org_member are Tier 1 Govern writes and need a bound token). Assigning a role to a person stays a console action.
Tools that read it afterwards: list_users (read, Govern), list_roles (read, Govern), get_my_permissions (read, Introspect). Connection details are in the MCP integration docs.
4. Knowledge check
Q1
SAML in ZopNight matches users to IdP by:
A. Username
B. Geographic region
C. Username + region
D. Email domain
Show answer
Correct: D. Each domain has its own SAML config; the user’s domain determines which IdP they are redirected to. This enables multi-domain orgs to use different IdPs per domain. Email domain is the routing key. This is what enables multi-IdP configurations after acquisitions or for partner federations.
Q2
A SAML assertion fails validation with “Invalid signature.” Most likely cause:
A. The user typed the wrong password at the identity provider
B. The IdP’s signing cert does not match the cert stored in ZopNight
C. A cloud provider error somewhere along the request chain
D. The user does not exist inside ZopNight at all yet today
Show answer
Correct: B. Most common after a cert renewal at the IdP that did not propagate. Send ZopDev the new thumbprint so the stored config is updated. Signature validation is between the IdP and ZopNight’s sign-in service; user credentials are not part of the check. Cert mismatch is the textbook cause; cert expiry is a related cause with the same symptom.
Q3
A new user signs in via SAML for the first time. What happens?
A. Manual ZopNight account creation is required first
B. Admin must approve
C. Account is auto-provisioned on successful SAML
D. The user is rejected on first login
Show answer
Correct: C. The account is created from the IdP’s email and name claims on the first successful sign-in. Roles and team membership are not taken from the IdP: an Admin manages them in ZopNight, in Settings → Organization and on the Teams page.
5. Apply
To set up or change SAML, ask ZopDev to configure it for your email domain, then test sign-in with one admin account before rollout. There is no SAML page in your org’s settings. Put each IdP cert’s renewal date in your calendar 90 days ahead; ZopNight does not track expiry.
For multi-IdP setups, each per-domain config is independent: ZopDev can deactivate or update one without affecting the others.
Related lessons
- L1: Pick your SSO
- L3: Google + GitHub OAuth (next)
- L4: Diagnosing SSO failures
- T4.M4.3.L1: Audit log: what gets recorded