Skip to main content

OAuth/OIDC Provider Config

Use this as a ready-to-paste framework_config.toml template for:

  • Google (built-in)
  • GitHub (built-in)
  • One generic OIDC provider (Auth0/Keycloak/Entra/custom)

Ready-to-paste framework_config.toml​

[auth.oauth]
enabled = true
providers = ["google", "github", "oidc-main"]

# Optional: override post-login destination
# post_login_redirect = "/desk"

[auth.oauth.google]
client_id = "${GOOGLE_CLIENT_ID}"
client_secret = "${GOOGLE_CLIENT_SECRET}"
redirect_uri = "${APP_BASE_URL}/api/v1/auth/oauth/google/callback"
scope = "openid email profile"

[auth.oauth.github]
client_id = "${GITHUB_CLIENT_ID}"
client_secret = "${GITHUB_CLIENT_SECRET}"
redirect_uri = "${APP_BASE_URL}/api/v1/auth/oauth/github/callback"
scope = "read:user user:email"

# Generic OIDC provider (preferred: discovery_url)
[auth.oauth.oidc-main]
client_id = "${OIDC_CLIENT_ID}"
client_secret = "${OIDC_CLIENT_SECRET}"
discovery_url = "${OIDC_DISCOVERY_URL}"
redirect_uri = "${APP_BASE_URL}/api/v1/auth/oauth/oidc-main/callback"
scope = "openid email profile"

# Optional for providers that need it:
# response_type = "code"
# response_mode = "query"

# If discovery is not available, use explicit endpoints instead:
# authorization_url = "https://idp.example.com/oauth2/authorize"
# token_url = "https://idp.example.com/oauth2/token"
# userinfo_url = "https://idp.example.com/oauth2/userinfo"

Required environment variables​

APP_BASE_URL=http://localhost:8888
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
OIDC_CLIENT_ID=...
OIDC_CLIENT_SECRET=...
OIDC_DISCOVERY_URL=https://your-idp/.well-known/openid-configuration

Provider callback URLs to register at each IdP​

  • Google: ${APP_BASE_URL}/api/v1/auth/oauth/google/callback
  • GitHub: ${APP_BASE_URL}/api/v1/auth/oauth/github/callback
  • Generic OIDC: ${APP_BASE_URL}/api/v1/auth/oauth/oidc-main/callback

How login works​

  1. Frontend shows providers from auth.oauth.providers.
  2. User clicks provider button -> /api/v1/auth/oauth/{provider}/start.
  3. Backend redirects to provider auth page.
  4. Provider redirects back to /api/v1/auth/oauth/{provider}/callback.
  5. Backend creates session cookie and redirects to Desk.

Notes​

  • This works without backend code changes for Google/GitHub/generic OIDC when config is correct.
  • For generic OIDC, discovery_url is preferred.
  • Keep provider key names stable (for example oidc-main) because the callback path includes that key.