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"

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 |

Microsoft Entra ID (Azure AD)

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]
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.

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.