OAuth/OIDC Provider Config

Use this as a ready-to-paste framework_config.toml template for Google, GitHub, and generic OIDC providers, including frontchannel logout and custom user ID mapping settings.

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"

# 1. Custom User ID Mapping Key (e.g. for Azure AD)
# Maps the custom claims (e.g. "oid" or "id") as the provider's unique user ID instead of "sub"
provider_id_key = "sub" 

# 2. Redirect URL for Upstream Profile Edits
# Used when local self-service is locked to redirect users to their corporate IDP profile portal
profile_url = "https://my-idp.company.com/account/profile"

# 3. OIDC Frontchannel Logout Settings
# The endpoint where the provider redirects the user after logging out from the IdP
frontchannel_logout_url = "${APP_BASE_URL}/api/v1/auth/oauth/oidc-main/logout/frontchannel"
end_session_endpoint = "https://your-idp/oauth2/v2.0/logout"

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

---

Configuring OIDC Frontchannel Logout

When a user logs out from the central Identity Provider (IdP) or another application in the enterprise, the IdP sends an asynchronous sign-out request to all active client applications to invalidate their local sessions.

1. Register the Frontchannel Logout URI: At your IdP (e.g. Keycloak or Azure AD), register your application's frontchannel logout callback: https://<your-app-domain>/api/v1/auth/oauth/<provider-key>/logout/frontchannel
2. Local Processing: When the IdP calls this URI, Framework M's web adapter intercepts it, extracts the session identifier (e.g. from the session cookie or backchannel parameters), destroys the matching session in the SessionStore, and clears client cookies.

---

Configuring Custom User ID Keys (e.g., Azure AD)

By default, OIDC adapters look up the unique user identifier under the standard OIDC subject claim ("sub"). Some providers, however, use different keys or custom attributes (such as "oid" in Azure AD/Microsoft Entra ID, or "id" in GitHub).

Use the provider_id_key configuration property under your provider config block to specify a custom ID claim:

[auth.oauth.oidc-main]
# ... standard settings ...
provider_id_key = "oid" # Instructs the adapter to parse Entra ID's Object ID

The OAuthAdapter will resolve this key dynamically from the token's decoded payload during user info extraction.