Skip to main content

​
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

​
Optional Variables

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

​
3. Restart Services

After updating the environment variables, restart your Kaneo services:

​
Example Configurations

​
Pocket ID

​
Keycloak

​
Auth0

​
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:
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:
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:
Some providers require openid scope as well:

​
Redirect URI Mismatch

Verify that your redirect URI in the OAuth provider matches exactly:
For example, if KANEO_API_URL=https://api.kaneo.example.com, the redirect URI should be:

​
Discovery URL

If your provider supports OpenID Connect, you can use the discovery URL to automatically configure most settings:
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