Authentication

ricochet uses OpenID Connect (OIDC) for authentication, allowing you to integrate with any OIDC-compliant identity provider.

Requirements

The OIDC provider must support:

• Claims: email and profile
• Grant Type: Authorization Code Flow

ricochet uses the subject identifier (sub) as the unique user ID. The email claim is collected for future SMTP integrations.

Configuration

Add the following to your ricochet-config.toml:

[auth.oidc]
issuer_url = "https://auth.example.com/"
client_id = "your_client_id"
client_secret = "your_client_secret"
redirect_url = "https://your-ricochet-domain.com/oauth/callback"
display_name_claim = "preferred_username"  # Optional, defaults to "preferred_username"
groups_claim = "groups"  # Optional, defaults to "groups"

Caution

The redirect URL must use the /oauth/callback path for compatibility with the ricochet cli.

Configuration Fields

Field	Required	Description
issuer_url	Yes	Your OIDC provider’s issuer URL. Must start with https://
client_id	Yes	OAuth client ID from your OIDC provider
client_secret	Yes	OAuth client secret from your OIDC provider
redirect_url	Yes	Callback URL where users are redirected after authentication. Must be https://your-domain/oauth/callback
display_name_claim	No	OIDC claim to use for display name. Defaults to preferred_username
groups_claim	No	Name of the OIDC claim that carries the user’s group memberships. The claim value may be an array of strings, a single string, or a comma-delimited string. Omit to disable group sync at login.
provider	No	Identity provider variant. Set to "entra" for Microsoft Entra ID; omit or set to "oidc" for all other providers. When "entra", groups_claim defaults to "groups" and background directory sync is enabled.
sync_interval	No	How often (in minutes) to run background group sync from the IdP directory. Only supported when provider = "entra". Omit to sync group memberships at login only.

SSO Groups

When groups_claim is set (defaulted to "groups"), ricochet reads the user’s group memberships from the configured claim of every ID token at login and mirrors them into the local user_groups table. You can then grant a role on a content item to a group name via the collaborators dialog, and any user whose ID token carried that group at their last login inherits the role.

A few practical points:

• Group memberships refresh on every login. A user who was added to a group in your IdP after their last ricochet login will not pick up the role until they sign in again.
• Names are byte-equal and case-sensitive. The group name typed in the collaborators dialog must match the string in the ID token exactly.

Microsoft Entra ID (Azure AD)

Issuer URL

When using Microsoft Entra ID, you must use the v2.0 issuer URL. The v1 issuer (https://sts.windows.net/{tenant-id}/) returns a non-standard discovery document that is incompatible with ricochet’s OIDC client.

[auth.oidc]
provider = "entra"
issuer_url = "https://login.microsoftonline.com/{tenant-id}/v2.0"
client_id = "your_client_id"
client_secret = "your_client_secret"
redirect_url = "https://your-ricochet-domain.com/oauth/callback"

Replace {tenant-id} with your Azure tenant ID.

Groups claim

Entra does not emit a groups claim by default — enable it explicitly on the app registration under Token configuration → Add groups claim. Pick Group ID (the default) or sAMAccountName depending on what your tenant supports.

Caution

Entra emits group object IDs (GUIDs) for cloud-only groups, even when sAMAccountName format is selected — sAMAccountName is only populated for groups synchronized from on-premises Active Directory via Entra Connect. If your groups were created directly in Entra, the value in the groups claim will be a GUID like a3f2c1e8-.... ricochet resolves these GUIDs to display names via Microsoft Graph when provider = "entra" is set.

Note

Background directory sync requires the app registration to have the Group.Read.All Microsoft Graph application permission granted by an administrator. Without it, ricochet can still sync group memberships at login from the ID token but cannot pull display names from the Graph API.

User avatars

Standard OIDC providers populate user avatars from the picture claim, but Entra omits that claim and serves photos only from Microsoft Graph. When provider = "entra" is set, ricochet fetches each user’s photo at login from GET /users/{id}/photo/$value, resizes it to a 128×128 PNG, and stores it without overwriting a user-uploaded avatar.

Note

Fetching avatars requires the app registration to have the User.Read.All Microsoft Graph application permission granted by an administrator (admin consent). The group permissions above do not cover /users/{id}/photo. Avatar fetching is best-effort — a missing permission, missing photo, or missing oid claim never blocks login.

Note

Entra applies a “group overage” limit at roughly 200 group memberships per user. Beyond that point Entra stops embedding the groups array in the token and references it via Microsoft Graph instead, which ricochet does not currently follow. Users with very large group memberships will appear to have no groups until this is implemented.

Requiring Authentication

By default, unauthenticated users can browse the “Explore” page and view public content. To require authentication for all access, enable the require_authentication option:

[auth]
require_authentication = true

Or via environment variable:

RICOCHET_AUTH__REQUIRE_AUTHENTICATION=true

Behavior

Setting	Unauthenticated User Access
require_authentication=false	Can view Explore page and public content only
require_authentication=true	Redirected to sign-in page on all routes

When require_authentication is enabled, users see a full-screen login page with SSO sign-in. When disabled (the default), unauthenticated users can browse public content but see a sign-in prompt in the sidebar to access protected features like deployment, API keys, and settings.

Next Steps

Learn about user roles Configure user roles and default permissions.