Tutorial
Set up single sign-on (SAML 2.0 or OIDC)
Set up SSO with Entra ID, Okta or Keycloak: create the app, enter the callback URL, test the login, then enforce SSO — without locking yourself out.
Last updated:
With single sign-on your team signs in through the identity provider you already run — Entra ID, Okta, Keycloak or anything else that speaks SAML 2.0 or OpenID Connect. Onboarding and offboarding then happen in exactly one place: with your IT team. SSO belongs to the Business Pro plan and takes minutes to set up — the only step that demands care is the enforcement at the end.
What you need
- The Business Pro plan (included in the Developer plan too) — see pricing.
- Admin rights in your Zuuna workspace and in your identity provider.
- A private browser window for testing before anything gets enforced.
1. Choose the method: SAML 2.0 or OpenID Connect
Each workspace has one SSO connection with one protocol. Both are equally secure: OIDC needs only three values (issuer, client ID, client secret) and is usually the faster route. SAML 2.0 is the classic every enterprise IT team knows. Entra ID supports both — pick whichever your IT already handles well.
2. Create the application in your identity provider
In Entra ID, Okta or Keycloak, create a new application for Zuuna and enter the callback URL there. Zuuna shows the exact URLs for your workspace in the SSO tab of the administration — they contain your workspace ID and look like this:
- OIDC redirect URI:
https://www.zuuna.de/api/sso/<workspace-id>/callback - SAML ACS URL:
https://www.zuuna.de/api/sso/<workspace-id>/acs - SAML entity ID and metadata URL:
https://www.zuuna.de/api/sso/<workspace-id>/metadata
Copy them straight out of Zuuna rather than typing them — one swapped character is the most common reason a test login fails.
3. Enter the values in Zuuna
Now the other direction, from the identity provider back into Zuuna. For OIDC: issuer URL, client ID and client secret — Zuuna stores the secret encrypted and never displays it again. For SAML: your provider's login URL (entry point), the IdP issuer and the signing certificate. You also set the default role that people get when they arrive via SSO for the first time — what the roles mean is covered in Invite your team and set roles.
4. Test the login
Enable the connection and test the sign-in via the SSO login URL from the SSO tab — in a private window, while password login is still available. Only once the test run goes through cleanly and you land in the workspace with the right role should you move on to enforcement.
5. Switch off password login (“Require SSO”)
With Require SSO, every login goes through your identity provider. Password sign-in is off — and a personally linked GitHub or GitLab login is refused server-side too, so nobody can route around the enforced IdP. But set up the exemption from step 6 first, then flip the switch.
6. Set exemptions — don't lock yourself out
Exemptions are per person: an exempted account may keep signing in with a password. That is exactly what they are for — if your identity provider goes down or the configuration breaks, you could not get back in to fix it otherwise. At least one admin account should stay exempted, with two-factor authentication switched on.
7. Optional: provision users automatically (SCIM)
With SCIM 2.0 your IT team manages access in the identity provider only. Generate a SCIM token in Zuuna (it is shown exactly once) and enter it in your identity provider together with the SCIM base URL https://www.zuuna.de/api/scim/v2/<workspace-id>. From then on new people appear in Zuuna automatically, and anyone removed in the IdP is deactivated automatically. Two honest notes: SCIM does not enforce your plan's seat limit on this path — provisioning can add members beyond Business Pro's 100. And the person who owns the workspace can never be deactivated via SCIM.
Troubleshooting
- The test login fails (SAML). Usually the entry point, issuer or certificate does not match the identity provider exactly. Copy all three values fresh from the IdP — and check that the certificate is still valid.
- You are locked out. Sign in with the exempted account using its password and switch Require SSO off until the connection is fixed. That is what exemptions are for — always create them before enforcing.
- SCIM returns 409. The email address belongs to an existing Zuuna account that is not a member of your workspace. Zuuna never adopts someone else's account — invite the person the regular way instead.
- SCIM returns 403 on deactivation. That is the person who owns the workspace. Transfer workspace ownership first, then the sync goes through.
Next steps
- GDPR-compliant project management — where your data lives and why that matters when choosing a vendor.
- Invite your team and set roles — the roles behind the SSO default role.
- All features at a glance — what else is in the Business Pro plan.
FAQ
Which identity providers work?
Anything that speaks SAML 2.0 or OpenID Connect — Entra ID, Okta or Keycloak, for example. Zuuna sticks to the standards; there is no special compatibility list.
Can I lock myself out?
Not if you set an exemption for your own account before enforcing — that is exactly what exemptions are for. The exempted account keeps signing in with a password, even if the identity provider is down.
Does SCIM deactivate people too?
Yes — SCIM syncs joiners and leavers. Anyone removed in the identity provider is deactivated in Zuuna automatically. The one exception is the person who owns the workspace: ownership has to be transferred first.
Which plan do I need?
Business Pro. The Developer plan includes SSO, Require SSO and SCIM as well. The details are on the pricing page.
Do I still need two-factor authentication?
With enforced SSO, your identity provider handles multi-factor sign-in — that is where it belongs. Zuuna's own 2FA enforcement is available on every plan; for exempted accounts that still sign in with a password, it remains strongly recommended.