Custom OAuth/OIDC

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:

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

2. Set Environment Variables

Add the following to your .env file:

# 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:

docker compose down
docker compose up -d

Example Configurations

Pocket ID

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

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

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. If you want to bypass the login page entirely and automatically redirect users to your identity provider, set:

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:

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:

CUSTOM_OAUTH_SCOPES=profile,email

Some providers require openid scope as well:

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:

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 links the OIDC identity to that existing account instead of failing with error=account_not_linked. GitHub, Google, Discord, and this custom provider are trusted to link because they verify the user’s email. Because Kaneo does not require email verification on password signup, linking also applies to unverified local accounts so OIDC users are not locked out. If your instance allows password registration alongside OIDC, set DISABLE_PASSWORD_REGISTRATION=true (or require email verification) so that nobody can pre-register another person’s email and have an OIDC login linked into it.

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

​Overview

​Configuration

​Required Variables

​Optional Variables

​Setup Steps

​1. Configure Your OAuth Provider

​2. Set Environment Variables

​3. Restart Services

​Example Configurations

​Pocket ID

​Keycloak

​Auth0

​Usage

​Auto-Login (Skip the Login Page)

​Troubleshooting

​”Invalid code verifier” Error

​Missing User Information

​Redirect URI Mismatch

​Discovery URL

​Account linking

​Security Notes