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 |
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
- Example:
- 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
# 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=false3. Restart Services
After updating the environment variables, restart your Kaneo services:
docker compose down
docker compose up -dExample 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,emailKeycloak
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_SCOPES=openid,profile,emailAuth0
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,emailUsage
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=falseSome 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,emailSome providers require openid scope as well:
CUSTOM_OAUTH_SCOPES=openid,profile,emailRedirect URI Mismatch
Verify that your redirect URI in the OAuth provider matches exactly:
{KANEO_API_URL}/api/auth/oauth2/callback/customFor example, if KANEO_API_URL=https://api.kaneo.example.com, the redirect URI should be:
https://api.kaneo.example.com/api/auth/oauth2/callback/customDiscovery 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-configurationThis 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