OIDC providers

OIDC providers let users sign in to Citadel with an external identity provider such as Keycloak, Auth0, Entra ID, Google Workspace, or another OpenID Connect provider.

Citadel uses the provider only to verify who the user is. After login, Citadel still manages:

sessions
roles
teams
resource access
permissions
audit and activity history

Local Citadel login remains available, including the local admin account.

OIDC connects Citadel to your identity provider. Your organization's sign-in administrator should supply the client settings and configure the callback.

Open Settings → OIDC Providers and add a provider.
Enter the issuer URL and client settings supplied by the sign-in administrator.
Register the callback URL shown by Citadel with that provider.
Test discovery, save the settings, and test sign-in with an approved account.
Confirm the new account has the intended Citadel access.

Keep a working local administrator account while testing. Signing in through a provider does not by itself grant access to every resource. The sections below explain discovery, claims, and account assignment.

When To Use OIDC

Use OIDC when your organization already manages users in a central identity provider and you want users to sign in with that account.

Good examples:

company SSO through Entra ID
self-hosted SSO through Keycloak
workspace login through Google Workspace
customer or team login through Auth0

Do not use OIDC as a replacement for Citadel permissions. The provider confirms identity; Citadel still decides what the user can see or change.

Before You Start

Create an application/client in your OIDC provider.

Use Authorization Code Flow with PKCE.

Configure the redirect URI shown by Citadel on the provider form. It will look like:

https://citadel.example.com/api/v1/authentication/oidc/<provider-id>/callback

The redirect URI must match exactly in the provider.

Recommended provider settings:

Flow: Authorization Code
PKCE: enabled
Scopes: openid profile email
ID token: enabled
Refresh tokens: not required for Citadel

Citadel does not store provider access tokens or provider refresh tokens.

Create A Provider

Open:

Settings -> OIDC Providers

Create a provider with:

Display name: button label shown on the login page, such as Company SSO
Name: stable internal name, such as company-sso
Issuer URL: provider issuer, such as https://sso.example.com/realms/company
Client ID: client/application id from the provider
Client secret: client secret, when the provider requires one
Scopes: usually openid profile email
Enabled: whether users can see and use this provider on the login page

Use Test discovery before enabling the provider. Citadel checks the issuer metadata and verifies that the provider exposes the required authorization, token, and JWKS endpoints.

Client secrets are encrypted at rest and are never shown again after saving.

The issuer URL must be reachable from the Citadel server, and the authorization URL returned by discovery must be reachable from users' browsers.

Enabled providers appear on the Citadel login page as buttons:

Continue with Company SSO
Continue with Keycloak

When a user clicks a provider:

Citadel redirects them to the provider.
The provider authenticates the user.
The provider redirects back to Citadel.
Citadel validates the provider response.
Citadel creates its normal session.
The user lands in the Citadel app.

The local username/password form remains available.

User Matching

Citadel identifies OIDC users by provider plus the provider's stable subject claim.

Citadel does not use email as the permanent identity. Email can change, but the provider subject should stay stable.

When a user signs in, Citadel checks:

Provider + subject

If that external identity is already linked, Citadel signs in the linked local user.

Auto-Provision Users

Auto-provisioning lets Citadel create a local user the first time an approved OIDC user signs in.

When disabled, unknown OIDC users are rejected unless email auto-linking is enabled and succeeds.

The Default Role picker only applies when auto-provisioning is enabled. When auto-provisioning is off, Citadel does not create new users, so there is no new user to receive that role.

Use auto-provisioning when your identity provider is already trusted to control who can access Citadel.

Recommended safe setup:

Enable Require verified email
Configure Allowed email domains
Configure a Required claim when your provider supports groups or roles
Assign a low-privilege default role, such as Viewer

Do not auto-provision users directly as admins.

Email Auto-Link

Email auto-link connects a new OIDC identity to an existing Citadel user when the email address matches.

This is useful when users already exist in Citadel and you are migrating them to SSO.

For safety:

Email auto-link is disabled by default.
Only enable it intentionally.
Keep Require verified email enabled.
Citadel should only link when the matching local email is unique.

Never auto-link users by unverified email.

Verified Email

When Require verified email is enabled, Citadel requires the provider to send:

email_verified = true

This affects:

auto-provisioning
email auto-linking

Keep this enabled unless your provider does not support the claim and you have another strong gate, such as a required group claim.

Allowed Email Domains

Allowed domains restrict who can be provisioned or linked.

Example:

company.com
engineering.company.com

With this setting, a user with alice@company.com can pass the domain gate. A user with alice@gmail.com cannot.

Use domains as a broad safety check. For tighter control, also use a required claim.

Required Claims

A required claim lets you restrict login to users with a provider claim value.

Example:

Claim name: groups
Required values: citadel-users

Only users whose groups claim contains citadel-users pass the gate.

For Keycloak, common claim names include:

groups
realm_access.roles
resource_access.<client-id>.roles

For Entra ID, common claim names include:

groups
roles

Provider claim formats vary. Use your provider's token preview/debug tools to confirm the exact claim name and value.

Default Role

The default role is assigned when Citadel auto-provisions a new user.

Use a low-privilege role first, such as:

Viewer

After the user exists, an admin can assign more roles, teams, or resource-specific access from the Access page.

The default role does not automatically update existing users every time they log in.

Teams And Roles

Citadel manages role and team membership after OIDC sign-in.

Admins manage access in:

Settings -> Access

OIDC claims can restrict sign-in, but they do not automatically map users to Citadel Roles or Teams. Manage those assignments from Settings → Access.

Disable A Provider

Disabling a provider hides it from the login page and prevents new logins through that provider.

Existing Citadel sessions are not automatically revoked when a provider is disabled. Users with active Citadel sessions may remain signed in until their Citadel session expires or they log out.

Use disable when: