Turn on single sign-on

Before you start

• This is an IT task. It assumes you know your way around your identity provider’s admin console. If you do not, do this together with whoever administers it, or hand them this page.
• Single sign-on (SSO) means people sign in to Zonitix with the account they already have at your identity provider: the service that holds your company’s accounts, such as Okta, Microsoft Entra ID or Google Workspace. OIDC and SAML are the two standard ways a provider and an app are connected; use whichever your provider’s administrator prefers.
• Your role must let you manage security settings. In the built-in set, administrators have that permission. The “security_analyst” role has it too; no group carries it, so an administrator gives it to a person by hand, as Roles, groups and permissions shows. You connect one identity provider per instance.
• Admin access to your identity provider, so you can create an application there.
• The people who will sign in must already exist in Zonitix (from a directory connection, SCIM or added by hand), unless you turn on just-in-time accounts in step 8.
• Keep at least one administrator who signs in with a password or passkey. SSO does not remove password sign-in, and that account is your way back in if the identity provider is misconfigured.

Start in Zonitix

1. 1

   Step 1: Open the SSO settings

   Go to Security & ComplianceSecurity SettingsSSO (OIDC / SAML). It is in the “Directory & Access” group of the Security Settings menu. The panel is called “Enterprise SSO”.

2. 2

   Step 2: Pick the protocol and your provider

   Choose “OIDC” or “SAML 2.0”, then pick your provider under “Identity provider”: Okta, Microsoft Entra ID, Google Workspace or Other IdP. The choice changes the setup hints on screen and the label on the sign-in button.

   Leave “Enable SSO login” off for now. You switch it on once everything is filled in.

   For OIDC, do steps 3 and 4. For SAML 2.0, skip to step 5.

If you chose OIDC (steps 3 and 4)

1. 3

   Step 3: Create the app in your provider

   The blue box tells you to create an “OIDC Web application” in your provider and register the exact “sign-in redirect URI” shown there. Copy it from the screen; do not type it.

2. 4

   Step 4: Copy the values back

   From your provider’s new app, fill in “Issuer URL” (must start with https), “Client ID” and “Client Secret”. The secret is stored encrypted and never shown again; once saved, the chip reads “Client secret is set”. Leave the secret blank later to keep it.

   Skip steps 5 and 6 and go on to step 7.

If you chose SAML 2.0 (steps 5 and 6)

1. 5

   Step 5: Give your provider the Zonitix values

   The blue box shows the “SP Entity ID (Audience)” (the name your provider knows Zonitix by) and the “ACS URL (Reply / Single sign-on URL)” (the Zonitix address your provider sends people back to after they sign in), plus numbered steps for the provider you picked. Follow those steps in your provider. People must be identified by their email address, and your provider must sign the assertion with SHA-256.

2. 6

   Step 6: Bring your provider’s details back

   Metadata is a small file your provider publishes that describes its side of the connection. Easiest: paste your provider’s metadata link into “IdP metadata URL” and click “LOAD FROM URL”, or use “UPLOAD METADATA XML”. This fills “IdP entity ID (issuer)”, “IdP SSO URL (HTTP-Redirect)” and “IdP signing certificate(s) (PEM)”. Nothing is saved yet. You can also type these three fields by hand. PEM is the text form of a certificate, starting with a line that reads BEGIN CERTIFICATE.

   After saving, a chip shows how long the certificate is valid. When your provider rotates its certificate, paste the new one (several are allowed during the changeover).

Finish and switch it on

1. 7

   Step 7: Optional: accept your provider’s MFA

   Administrators, and anyone holding the permission to manage security, to manage users or to mark approved invoices as paid, always need a second factor at sign-in. No group exemption lifts that, and neither does ticking Trust this device for 30 days. That holds after single sign-on too. If your provider proves MFA, Zonitix accepts it; if it does not, Zonitix asks for its own. Only fill “MFA-satisfying authentication contexts (optional)” if your provider sends a specific value after MFA that you want counted.

2. 8

   Step 8: Decide on just-in-time accounts

   “Create accounts on first SSO sign-in (JIT)” is off by default. JIT, or just-in-time, means Zonitix creates the account the first time someone signs in instead of beforehand. Off means only people who already exist in Zonitix can sign in; anyone else is refused.

   If you turn it on, list your “Allowed email domains” (exact match only, so a subdomain is not covered), then pick a “Default role” and “Default group”. The administrator role, and any role or group that carries the permission to manage security, to manage users or to mark approved invoices as paid, cannot be the default. These are the same people who always need a second factor at sign-in. Keep it minimal: anyone your provider signs in with a listed domain gets an account.

3. 9

   Step 9: Turn it on and save

   Switch on “Enable SSO login” and click “SAVE SSO SETTINGS”. Zonitix may ask you to confirm it is you before saving. The change is recorded in the audit log.

4. 10

   Step 10: Test before you tell anyone

   Keep this tab open. In a private browser window, open your Zonitix sign-in page. You should see “SIGN IN WITH OKTA”, “SIGN IN WITH MICROSOFT”, “SIGN IN WITH GOOGLE” or “SIGN IN WITH SSO”. Sign in with a test user assigned to the app in your provider.

   If it fails, switch “Enable SSO login” off in the open tab and save; password sign-in keeps working the whole time.

What you should see

If something goes wrong

"Your identity provider signed you in, but there is no active account for your email here. If you are new, your account may not be ready yet — ask your administrator to check that it exists and is active."

The person is not in Zonitix, or their account is not active. Sync or add them first, or turn on just-in-time accounts for their email domain. A deactivated or offboarded account is never reopened by SSO.

"Single sign-on is not set up correctly on this instance. Ask your administrator to check the SSO settings."

SSO is switched off, its settings are incomplete, or Zonitix could not reach your provider. Open Security Settings, SSO (OIDC / SAML), check every field for the protocol you chose, and save again.

"That single sign-on attempt expired or was started in another tab. Start it again from this page."

A sign-in attempt lasts 10 minutes and must finish in the same browser that started it. Go back to the Zonitix sign-in page and click the SSO button again.

"Single sign-on did not complete. Try again; if it keeps happening, contact your administrator."

Usually the redirect URI or ACS URL in your provider does not match the one on the Zonitix screen exactly. Copy the values again from Security Settings and retry. For SAML, also check that your provider signs the assertion with SHA-256.

Saving fails with "Issuer must be an https URL." or "Client ID is required."

OIDC needs both before SSO can be enabled. Copy the issuer from your provider, starting with https.

Saving fails with "IdP entity ID (issuer) is required.", "IdP SSO URL is required." or "At least one IdP signing certificate is required."

SAML needs all three before SSO can be enabled. Load your provider’s metadata again, or fill the missing field by hand.

Saving fails with a message that the JIT default role or group "is privileged".

Pick a role or group that is not the administrator role and does not carry the permission to manage security, to manage users or to mark approved invoices as paid, or choose No role / No group.

Still stuck? See When something goes wrong, or Contact Zonitix support.

Where next

• Push users with SCIM
• Connect Okta, Entra or Google
• Check and adjust MFA
• Add your admins