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

> Configure custom OAuth providers like GitHub Google and Discord in Kaneo using environment variables. Enable secure authentication in minutes with this quick guide.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-06

---

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

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/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

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

```bash

# .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`](https://github.com/usekaneo/kaneo/blob/main/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

```bash

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

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/github-sso-env.ts) | GitHub credential loader and validator |
| [`apps/web/src/components/auth/sso-providers.tsx`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/components/auth/sso-providers.tsx) | React component rendering provider buttons |
| [`apps/web/src/lib/auth-client.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.