workboardworkboard

Custom OAuth/OIDC

Overview

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

  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 Workboard 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=workboard-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.

Auto-Login (Skip the Login Page)

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