How to Configure Custom OAuth Providers (GitHub, Google, and Discord) in Kaneo

Set OAuth credentials via environment variables in Kaneo to enable GitHub, Google, or any custom provider like Discord within minutes.

Kaneo supports multiple authentication pathways through dedicated OAuth 2.0 / OpenID Connect integrations. The configuration is entirely environment-driven—no code changes required—making it straightforward to configure custom OAuth providers in Kaneo for teams using external identity providers.

GitHub OAuth Configuration

GitHub has first-class support in Kaneo with dedicated environment variables and automatic UI detection.

Step 1: Create a GitHub OAuth App

Navigate to GitHub Developer Settings > OAuth Apps > New OAuth App and configure:

• Authorization callback URL: {KANEO_API_URL}/api/auth/callback/github

Step 2: Configure Environment Variables

Add these to your .env file:

GITHUB_OAUTH_CLIENT_ID=your-github-client-id
GITHUB_OAUTH_CLIENT_SECRET=your-github-client-secret

Kaneo also accepts legacy variable names (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET) for backward compatibility. When detected, Kaneo automatically renders a "Continue with GitHub" button on the sign-in page.

Source reference: The apps/api/src/utils/github-sso-env.ts utility reads these variables at startup and validates their presence.

Google OAuth Configuration

Google follows a similar dedicated integration pattern.

Step 1: Configure Google Cloud Console

1. Enable the Google Sign-In API in your Google Cloud project
2. Create an OAuth 2.0 Client ID under Credentials
3. Add the redirect URI: {KANEO_API_URL}/api/auth/callback/google

Step 2: Set Environment Variables

GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

After restarting the Kaneo services, the Google sign-in option appears automatically on the authentication page.

Discord OAuth via Custom OAuth/OIDC

Discord has no built-in social provider entry in Kaneo, but integrates seamlessly through the generic Custom OAuth/OIDC mechanism. This same approach works for any provider supporting standard OAuth 2.0 or OIDC.

Required Environment Variables

Variable	Purpose	Discord Example
CUSTOM_OAUTH_CLIENT_ID	Application client ID	1234567890abcdef
CUSTOM_OAUTH_CLIENT_SECRET	Application client secret	abcdef1234567890
CUSTOM_OAUTH_AUTHORIZATION_URL	Provider's authorize endpoint	https://discord.com/api/oauth2/authorize
CUSTOM_OAUTH_TOKEN_URL	Provider's token endpoint	https://discord.com/api/oauth2/token
CUSTOM_OAUTH_USER_INFO_URL	User info endpoint (optional)	https://discord.com/api/users/@me

Optional Configuration Variables

• CUSTOM_OAUTH_DISCOVERY_URL — OIDC discovery document URL
• CUSTOM_OAUTH_SCOPES — Default is profile,email; use identify,email for Discord
• CUSTOM_OAUTH_RESPONSE_TYPE — Usually code
• CUSTOM_AUTH_PKCE — Set to false for Discord (no PKCE support)
• CUSTOM_OAUTH_LOGOUT_URL — IdP logout URL
• CUSTOM_OAUTH_AUTO_LOGIN — Skip login page with true

Complete Discord Configuration

# .env — Discord via Custom OAuth

CUSTOM_OAUTH_CLIENT_ID=YOUR_DISCORD_CLIENT_ID
CUSTOM_OAUTH_CLIENT_SECRET=YOUR_DISCORD_CLIENT_SECRET
CUSTOM_OAUTH_AUTHORIZATION_URL=https://discord.com/api/oauth2/authorize
CUSTOM_OAUTH_TOKEN_URL=https://discord.com/api/oauth2/token
CUSTOM_OAUTH_USER_INFO_URL=https://discord.com/api/users/@me
CUSTOM_OAUTH_SCOPES=identify,email
CUSTOM_AUTH_PKCE=false

Important: Discord does not support PKCE (CUSTOM_AUTH_PKCE=false is required).

Frontend Rendering

When CUSTOM_OAUTH_CLIENT_ID is detected, the apps/web/src/components/auth/sso-providers.tsx component renders a "Continue with OIDC" button. Clicking it initiates flow through /api/auth/oauth2/authorize/custom, which constructs the authorization URL from your environment variables.

Complete Multi-Provider Configuration Example

# Core Kaneo URLs

KANEO_API_URL=http://localhost:1337
KANEO_CLIENT_URL=http://localhost:5173

# GitHub

GITHUB_OAUTH_CLIENT_ID=gh-client-id
GITHUB_OAUTH_CLIENT_SECRET=gh-client-secret

# Google

GOOGLE_CLIENT_ID=google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=google-client-secret

# Discord (Custom OAuth)

CUSTOM_OAUTH_CLIENT_ID=discord-client-id
CUSTOM_OAUTH_CLIENT_SECRET=discord-client-secret
CUSTOM_OAUTH_AUTHORIZATION_URL=https://discord.com/api/oauth2/authorize
CUSTOM_OAUTH_TOKEN_URL=https://discord.com/api/oauth2/token
CUSTOM_OAUTH_USER_INFO_URL=https://discord.com/api/users/@me
CUSTOM_OAUTH_SCOPES=identify,email
CUSTOM_AUTH_PKCE=false

Deployment Checklist

1. Add variables to .env or your container orchestration platform
2. Restart the API and web services to load new configuration
3. Verify provider buttons appear at /auth/sign-in
4. Test complete authentication flow including callback handling

SSO-Only Mode Considerations

When enabling SSO-only access:

DISABLE_LOGIN_FORM=true

# OR

CUSTOM_OAUTH_AUTO_LOGIN=true

Ensure all existing local accounts have verified emails attached. Users without linked email addresses will receive error=account_not_linked on login attempts.

Key Implementation Files

File	Purpose
.env.example	Complete template of all supported environment variables
apps/api/src/utils/github-sso-env.ts	GitHub credential loader and validator
apps/web/src/components/auth/sso-providers.tsx	React component rendering provider buttons
apps/web/src/lib/auth-client.ts	Generic OAuth client initialization for custom providers

Summary

• GitHub and Google use dedicated environment variables with automatic UI detection
• Discord and other providers integrate through the Custom OAuth/OIDC generic mechanism
• All configuration is environment-driven—no code modifications required
• Set CUSTOM_AUTH_PKCE=false for providers like Discord that lack PKCE support
• Restart services after any environment variable changes

Frequently Asked Questions

How do I add a provider that Kaneo doesn't natively support?

Use the Custom OAuth/OIDC variables (CUSTOM_OAUTH_*). Any provider implementing standard OAuth 2.0 or OpenID Connect works—including Discord, Okta, Auth0, or Keycloak. Supply the authorization URL, token URL, client credentials, and optional discovery URL.

Why doesn't my Discord login show a "Continue with Discord" button?

Kaneo renders "Continue with OIDC" for all custom providers. The button label is generic because the custom flow accepts any identity provider. You can customize the UI in apps/web/src/components/auth/sso-providers.tsx if needed.

What happens if I enable both GitHub and Google?

Kaneo displays all configured providers simultaneously. Users choose their preferred authentication method. Multiple providers can coexist without conflict.

Can I disable password login entirely?

Yes. Set DISABLE_LOGIN_FORM=true to remove the username/password form, or set CUSTOM_OAUTH_AUTO_LOGIN=true to immediately redirect to the configured custom provider. Ensure users have linked email addresses to avoid account_not_Linked errors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}