Configure SSO

Hook QuickZTNA to your identity provider so users sign in with their corporate credentials. Supports OIDC (most providers), SAML 2.0 (enterprise), and SCIM 2.0 for automated user provisioning. SSO is free on every plan — SCIM is Business+.

Supported providers

Anything that speaks OIDC or SAML 2.0 works. Tested with:

• Okta — OIDC + SAML + SCIM
• Microsoft Entra ID (Azure AD) — OIDC + SAML + SCIM
• Google Workspace — OIDC + SCIM (SAML via Cloud Identity)
• Auth0 — OIDC + SAML
• JumpCloud, OneLogin, Ping Identity, Keycloak — OIDC + SAML
• GitHub OAuth + Google OAuth — for developer-first teams (no SSO cost)

Generic OIDC setup

Most OIDC providers follow this pattern. Steps differ slightly per IdP.

1. In your IdP, create an OIDC application (a.k.a. client).
2. Set redirect URI to https://login.quickztna.com/api/sso-auth/callback_oidc.
3. Note the client ID, client secret, issuer URL.
4. Enable scopes: openid email profile groups.
5. In QuickZTNA dashboard: Admin → SSO → Add OIDC provider. Paste client ID, secret, issuer.
6. Set org slug — e.g. acme. Users sign in via acme.zt.net or by clicking "SSO" on the login page.
7. Save. Test with a user account.

$ curl https://login.quickztna.com/api/db/sso_configurations \
    -H "Authorization: Bearer $QZ_API_KEY" \
    -d '{
      "rows": [{
        "org_id": "org_9fX2kR",
        "provider": "oidc",
        "issuer": "https://acme.okta.com",
        "client_id": "0oabcdefghijk",
        "client_secret": "secret-value",
        "scopes": "openid email profile groups"
      }]
    }'

Okta — OIDC step-by-step

1. Okta admin → Applications → Create App Integration
2. Sign-in method: OIDC — OpenID Connect. Application type: Web Application.
3. Name: "QuickZTNA". Grant types: Authorization Code.
4. Sign-in redirect URI: https://login.quickztna.com/api/sso-auth/callback_oidc
5. Sign-out redirect URI: https://login.quickztna.com/auth
6. Assignments: groups that should have access.
7. Save. Copy Client ID + Client Secret.
8. Okta API → Authorization Servers → default → Claims → add groups claim of type Groups with filter matching your groups.
9. In QuickZTNA dashboard: Admin → SSO → Add OIDC. Issuer: https://<your-okta>.okta.com.

Microsoft Entra ID (Azure AD) — OIDC

1. Entra admin → App registrations → New registration
2. Name: "QuickZTNA". Supported account types: single tenant.
3. Redirect URI (Web): https://login.quickztna.com/api/sso-auth/callback_oidc
4. Certificates & secrets → New client secret. Copy the value immediately.
5. API permissions → Microsoft Graph → email, profile, openid, User.Read, GroupMember.Read.All. Grant admin consent.
6. Token configuration → Add groups claim → Security groups.
7. Note Application (client) ID + Directory (tenant) ID.
8. In QuickZTNA: Issuer https://login.microsoftonline.com/<tenant-id>/v2.0.

Google Workspace — OIDC

1. Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Application type: Web application.
3. Authorized redirect URI: https://login.quickztna.com/api/sso-auth/callback_oidc
4. Enable Admin SDK API for group membership.
5. Grant domain-wide delegation for groups.
6. In QuickZTNA: Issuer https://accounts.google.com.

SAML 2.0 setup

For providers or orgs that mandate SAML over OIDC.

1. In QuickZTNA dashboard: Admin → SSO → Add SAML provider. Note the Entity ID + ACS URL.
2. In your IdP: create a new SAML app using those values.
3. IdP → export metadata XML.
4. Upload the metadata XML in QuickZTNA, or paste the SSO URL + signing cert.
5. Map attributes:
   • NameID → email
   • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress → email
   • groups → groups (multi-value)
6. Test SSO flow end-to-end.

SCIM 2.0 provisioning (Business+)

SCIM automates user lifecycle — new hires get tailnet access on day one; terminated users lose access immediately.

1. QuickZTNA dashboard → Admin → SCIM → Generate bearer token. Copy immediately.
2. SCIM endpoint URL: https://login.quickztna.com/api/scim
3. In your IdP's SCIM config:
   • Base URL: the URL above
   • Bearer token: the generated token
   • Supported operations: Create, Read, Update, Deactivate, Delete users; Create/Update/Delete groups
4. Set attribute mappings. Minimum: userName (email), name.givenName, name.familyName, emails[0].value.
5. For groups: map your IdP groups to QuickZTNA groups. QuickZTNA uses group names in ACLs.
6. Enable provisioning. Test with a single user first.

Group → role mapping

Map IdP groups to QuickZTNA roles in Admin → SSO → Group mappings:

{
  "acme-zt-owners":   "owner",
  "acme-zt-admins":   "admin",
  "acme-zt-members":  "member",
  "acme-zt-readonly": "member"
}

Groups not mapped default to member. Admins can override per user from the Members page.

JIT user provisioning

If a user authenticates via SSO but doesn't exist yet in QuickZTNA, the system creates them on the fly — using the email from the ID token. Group claims determine their initial role.

Disable this if you want strict pre-provisioning: Admin → Security → JIT user provisioning off.

Adding TOTP MFA on top of SSO

SSO already enforces your IdP's MFA. If you want an extra factor at the QuickZTNA layer:

• Admin enables require_mfa org-wide
• Users enrol a TOTP authenticator (Google Authenticator, Authy, 1Password)
• Every login prompts for a 6-digit code after SSO completes
• Replay-protected (used codes cached 90s)

Troubleshooting

See also

• Security: authentication model — how JWTs + refresh tokens fit with SSO
• API: SSO + SCIM endpoints
• Features: identity & provisioning — what's free vs paid