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

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:

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

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.

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