Skip to main content

​
Overview

Kaneo supports custom OAuth 2.0 and OpenID Connect (OIDC) providers, allowing you to connect an identity provider such as Keycloak, Auth0, Okta, Azure AD, or self-hosted solutions like Pocket ID. Use the public callback URL shown below. If KANEO_API_URL already ends in /api, do not add another /api segment.

​
Configuration

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

​
Provider settings

If you use a discovery URL, the provider can supply the authorization, token, and user-info endpoints. You still need the client ID and secret.

​
Optional settings

​
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: https://kaneo.example.com/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. Apply the configuration

After updating the environment variables, recreate the bundled application container:

​
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, Kaneo redirects visitors to the custom provider. If CAPTCHA is configured, it first shows the sign-in page so the visitor can complete the challenge. Verify existing local accounts before enabling this option; see account linking below.

​
Troubleshooting

​
”Invalid code verifier” Error

Check that the provider and Kaneo both use PKCE and that the callback returns to the same public instance URL. Keep PKCE enabled for providers that support it:
Only set CUSTOM_AUTH_PKCE=false when your provider’s documentation requires a flow without PKCE.

​
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 a separately hosted API at https://api.kaneo.example.com, use:

​
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, Kaneo can link the OIDC identity to that account. The provider must return a verified email claim; being configured does not make an unverified email trusted. Configure your identity provider to return email_verified: true only after establishing ownership of the email address. An unverified claim cannot satisfy email-based invitation matching either. 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 (which also blocks new OTP, magic-link and guest accounts) 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, recreate the Kaneo container, 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