> ## Documentation Index
> Fetch the complete documentation index at: https://kaneo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom OAuth/OIDC

> Configure Kaneo with your custom OpenID Connect (OIDC) provider.

## Overview

Kaneo supports custom OAuth 2.0 and OpenID Connect (OIDC) providers, allowing you to integrate with any standards-compliant identity provider such as Keycloak, Auth0, Okta, Azure AD, or self-hosted solutions like Pocket ID.

## Configuration

To configure a custom OAuth/OIDC provider, you need to set the following environment variables in your `.env` file:

### Required Variables

| Variable                         | Description                            | Example                                    |
| -------------------------------- | -------------------------------------- | ------------------------------------------ |
| `CUSTOM_OAUTH_CLIENT_ID`         | OAuth client ID from your provider     | `2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0`     |
| `CUSTOM_OAUTH_CLIENT_SECRET`     | OAuth client secret from your provider | `NzDjplDsdQyP062wTmkZ8kyiaziBag0N`         |
| `CUSTOM_OAUTH_AUTHORIZATION_URL` | Authorization endpoint URL             | `https://id.example.com/authorize`         |
| `CUSTOM_OAUTH_TOKEN_URL`         | Token exchange endpoint URL            | `https://id.example.com/api/oidc/token`    |
| `CUSTOM_OAUTH_USER_INFO_URL`     | User info endpoint URL                 | `https://id.example.com/api/oidc/userinfo` |

### Optional Variables

| Variable                     | Description                                                          | Default                                  |
| ---------------------------- | -------------------------------------------------------------------- | ---------------------------------------- |
| `CUSTOM_OAUTH_DISCOVERY_URL` | OpenID Connect discovery document URL                                | -                                        |
| `CUSTOM_OAUTH_SCOPES`        | Comma-separated list of OAuth scopes                                 | `profile,email`                          |
| `CUSTOM_OAUTH_RESPONSE_TYPE` | OAuth response type                                                  | `code`                                   |
| `CUSTOM_AUTH_PKCE`           | Enable/disable PKCE (Proof Key for Code Exchange)                    | `true`                                   |
| `CUSTOM_OAUTH_LOGOUT_URL`    | Logout endpoint URL (optional)                                       | `https://id.example.com/api/oidc/logout` |
| `CUSTOM_OAUTH_AUTO_LOGIN`    | Auto-redirect to the custom OAuth provider, bypassing the login page | `false`                                  |

## Setup Steps

### 1. Configure Your OAuth Provider

First, create an OAuth 2.0 or OIDC application in your identity provider:

1. Log in to your identity provider's admin console
2. Create a new OAuth 2.0 or OIDC application
3. Set the redirect URI to: `{KANEO_API_URL}/api/auth/oauth2/callback/custom`
   * Example: `https://api.kaneo.example.com/api/auth/oauth2/callback/custom`
4. Copy the client ID and client secret
5. Note the authorization, token, and userinfo endpoint URLs

### 2. Set Environment Variables

Add the following to your `.env` file:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Custom OAuth/OIDC Configuration
CUSTOM_OAUTH_CLIENT_ID=your-client-id
CUSTOM_OAUTH_CLIENT_SECRET=your-client-secret
CUSTOM_OAUTH_AUTHORIZATION_URL=https://your-idp.com/authorize
CUSTOM_OAUTH_TOKEN_URL=https://your-idp.com/oauth/token
CUSTOM_OAUTH_USER_INFO_URL=https://your-idp.com/oauth/userinfo
CUSTOM_OAUTH_LOGOUT_URL=https://your-idp.com/oauth/logout

# Optional: Use discovery URL for automatic configuration
CUSTOM_OAUTH_DISCOVERY_URL=https://your-idp.com/.well-known/openid-configuration

# Optional: Customize scopes
CUSTOM_OAUTH_SCOPES=profile,email,openid

# Optional: Disable PKCE if your provider doesn't support it
CUSTOM_AUTH_PKCE=false
```

### 3. Restart Services

After updating the environment variables, restart your Kaneo services:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose down
docker compose up -d
```

## Example Configurations

### Pocket ID

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_OAUTH_CLIENT_ID=2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0
CUSTOM_OAUTH_CLIENT_SECRET=NzDjplDsdQyP062wTmkZ8kyiaziBag0N
CUSTOM_OAUTH_AUTHORIZATION_URL=https://4c6332d2.demo.pocket-id.org/authorize
CUSTOM_OAUTH_TOKEN_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/token
CUSTOM_OAUTH_USER_INFO_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/userinfo
CUSTOM_OAUTH_DISCOVERY_URL=https://4c6332d2.demo.pocket-id.org/.well-known/openid-configuration
CUSTOM_OAUTH_SCOPES=profile,email
```

### Keycloak

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_OAUTH_CLIENT_ID=kaneo-client
CUSTOM_OAUTH_CLIENT_SECRET=your-secret-here
CUSTOM_OAUTH_DISCOVERY_URL=https://keycloak.example.com/realms/your-realm/.well-known/openid-configuration
CUSTOM_OAUTH_LOGOUT_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/logout
CUSTOM_OAUTH_SCOPES=openid,profile,email
```

### Auth0

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_OAUTH_CLIENT_ID=your-client-id
CUSTOM_OAUTH_CLIENT_SECRET=your-client-secret
CUSTOM_OAUTH_AUTHORIZATION_URL=https://your-tenant.auth0.com/authorize
CUSTOM_OAUTH_TOKEN_URL=https://your-tenant.auth0.com/oauth/token
CUSTOM_OAUTH_USER_INFO_URL=https://your-tenant.auth0.com/userinfo
CUSTOM_OAUTH_SCOPES=openid,profile,email
```

## Usage

Once configured, users will see a "Continue with OIDC" button on the sign-in page. The system will automatically remember the last used login method for each user.

### Auto-Login (Skip the Login Page)

If you want to bypass the login page entirely and automatically redirect users to your identity provider, set:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_OAUTH_AUTO_LOGIN=true
```

When enabled, users visiting the sign-in page will be immediately redirected to your custom OAuth provider without seeing the Kaneo login page. This is ideal for organizations that use a single identity provider for all authentication.

## Troubleshooting

### "Invalid code verifier" Error

This error typically indicates a PKCE configuration issue. Try setting:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_AUTH_PKCE=false
```

Some OAuth providers don't support PKCE or have it disabled by default.

### Missing User Information

Ensure your OAuth scopes include at least `profile` and `email`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_OAUTH_SCOPES=profile,email
```

Some providers require `openid` scope as well:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_OAUTH_SCOPES=openid,profile,email
```

### Redirect URI Mismatch

Verify that your redirect URI in the OAuth provider matches exactly:

```
{KANEO_API_URL}/api/auth/oauth2/callback/custom
```

For example, if `KANEO_API_URL=https://api.kaneo.example.com`, the redirect URI should be:

```
https://api.kaneo.example.com/api/auth/oauth2/callback/custom
```

## Discovery URL

If your provider supports OpenID Connect, you can use the discovery URL to automatically configure most settings:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
CUSTOM_OAUTH_DISCOVERY_URL=https://your-idp.com/.well-known/openid-configuration
```

This will automatically discover the authorization, token, and userinfo endpoints. However, you still need to provide the client ID and secret.

## Account linking

When a user signs in with this provider using an email that already belongs to a Kaneo account (for example one created with email and password), Kaneo can link the OIDC identity to that existing account instead of failing with `error=account_not_linked`. GitHub, Google, and Discord are trusted because they verify email ownership. Kaneo also treats the configured custom provider as trusted, but it cannot verify the provider's email claims itself. Only use a custom provider that guarantees ownership of every returned email address; otherwise, an attacker-controlled email claim could be linked to an existing verified account.

For safety, Kaneo only links to an existing local account if that account's email has already been verified. This prevents someone from pre-registering another person's email with a password account and retaining access after the real owner signs in through OIDC. If your instance allows password registration alongside OIDC, consider setting `DISABLE_PASSWORD_REGISTRATION=true` or requiring email verification for password users to avoid account-linking surprises.

On existing installations, local accounts created before this requirement may still have an unverified email. Those users will receive `error=account_not_linked` until they verify the local account. Before enforcing SSO-only access, keep the login form available so affected users can sign in with an email OTP or magic link, which verifies the email. If users are already locked out, temporarily set `DISABLE_LOGIN_FORM=false` and `CUSTOM_OAUTH_AUTO_LOGIN=false`, restart Kaneo, and have them complete an email sign-in before enabling SSO-only access again.

## Security Notes

* Always use HTTPS in production
* Keep your client secret secure and never commit it to version control
* Enable PKCE when possible for enhanced security
* Use the most restrictive scopes necessary for your use case