Single Sign-On (SSO / OIDC)

Overview

Anzen supports Single Sign-On via OpenID Connect (OIDC). This allows your users to authenticate using an external identity provider (IdP) such as Microsoft Entra ID (Azure AD), Okta, Keycloak, Google Workspace, or any OIDC-compliant provider.

SSO is available on the Professional and Enterprise plans. Once configured, users can sign in via SSO from both the Management Interface and the Service Portal. Configuration is done per-tenant by a superadmin via the management interface under Settings → SSO / OIDC.

Authentication Flow

Anzen uses the Authorization Code flow (server-side):

1. User clicks “Sign in with SSO” on the login page.
2. Anzen redirects the user’s browser to your IdP’s authorization endpoint.
3. The user authenticates with the IdP (password, MFA, etc.).
4. The IdP redirects back to Anzen with an authorization code.
5. Anzen exchanges the code for tokens using the client_id and client_secret (server-side, confidential client).
6. Anzen reads the user’s identity from the ID token / userinfo endpoint and creates or updates the local user account.

IdP Configuration

When registering Anzen as a client/application in your identity provider, use the following settings:

Replace <your-workspace> with your actual workspace slug (e.g. acme).

Important: Two redirect URIs are required because Anzen has two frontends that support SSO — the Management Interface (at /management/) and the Service Portal (at /). Both must be registered in your identity provider.

Anzen Configuration

In the Anzen management interface under Settings → SSO / OIDC, provide:

Group Mapping

Anzen can automatically assign users to groups based on their IdP claims. This is configured in the SSO settings under Group Mapping.

Configuration

How It Works

1. On each SSO login, Anzen reads the group claim from the IdP token (ID token or userinfo).
2. Default groups are always assigned to the user.
3. Each IdP group name is matched against the configured mappings.
4. Matching Anzen groups are added to the user’s group membership.
5. Group sync is additive — manually assigned groups are never removed.

Common Group Claims by Provider

Discovery URL Examples

User Provisioning

When a user authenticates via SSO for the first time, Anzen automatically creates a local user account using the email and name from the IdP’s claims. The user does not need a local password — they can only sign in via SSO.

Auto-provisioned users count towards your plan’s user limit. On the Starter plan, SSO user provisioning is blocked once the 5-user limit is reached.

Security Notes

• The client secret is stored encrypted in the database and is never exposed via the API (only a masked version is shown).
• CSRF protection is enforced via a random state parameter on each authorization request.
• Token exchange happens server-side — the client secret is never sent to the browser.
• PKCE is not used because Anzen acts as a confidential (server-side) client. If your IdP requires PKCE, disable that requirement for this client.
• Local password login remains available alongside SSO. Users who were provisioned via SSO do not have a local password and can only sign in via SSO.

Troubleshooting

• Discovery URL test fails: Ensure the URL ends with /.well-known/openid-configuration and is reachable from the Anzen server.
• Redirect mismatch: Both redirect URIs must be registered in your IdP: /management/oidc/callback for the Management Interface and /oidc/callback for the Service Portal.
• Missing email claim: Ensure the email scope is granted and the IdP includes the email claim in the ID token or userinfo response.
• User limit reached: On Starter plan, SSO login will fail if there are already 5 users. Upgrade to Professional for unlimited users.