From f7c5efc7b275c974b7ee936b2cbb5fc878316dbf Mon Sep 17 00:00:00 2001 From: Marian Date: Mon, 20 Jul 2026 16:46:16 +0000 Subject: [PATCH] docs: document the BAMBUDDY_OIDC_* variables in .env.example Follows the BAMBUDDY_LOCAL_LOGIN block's style: what it is for, when it activates, and the two things an operator cannot guess from the variable names -- that removing the config disables rather than deletes the provider, because deleting would permanently drop every account link, and that the UI shows it read-only because startup would overwrite an edit anyway. Also states why auto-link is refused without verified emails, since that is the one setting that will be silently skipped if someone gets it wrong. Refs #2593 --- .env.example | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/.env.example b/.env.example index 572ab248d..7a2227b2e 100644 --- a/.env.example +++ b/.env.example @@ -66,3 +66,43 @@ LOG_TO_FILE=true # LDAP is governed by its own ldap_enabled toggle and is not affected. # Leave unset for normal operation. # BAMBUDDY_LOCAL_LOGIN=true + +# --- OIDC provider from the environment (#2593) ------------------------------ +# Defines ONE OIDC provider declaratively, for deployments that are managed by +# compose files or GitOps and never touch the settings UI. Providers created in +# the UI are unaffected and keep working alongside this one. +# +# Activates only when all four required vars below are set; an empty value +# counts as unset. The provider is written on startup and re-applied on every +# boot, so the UI shows it as read-only and the API refuses to change it -- an +# edit there would be reverted at the next restart anyway. +# +# Removing the vars DISABLES the provider rather than deleting it: accounts +# linked to it would otherwise lose their link permanently. Re-adding the vars +# enables it again with those links intact. +# +# If you lock yourself out, BAMBUDDY_LOCAL_LOGIN=true above is the way back in. +# +# Required: +# BAMBUDDY_OIDC_NAME=Keycloak +# BAMBUDDY_OIDC_ISSUER_URL=https://sso.example.com/realms/main +# BAMBUDDY_OIDC_CLIENT_ID=bambuddy +# BAMBUDDY_OIDC_CLIENT_SECRET=your-client-secret +# +# Optional, shown with their defaults: +# BAMBUDDY_OIDC_SCOPES=openid email profile +# BAMBUDDY_OIDC_ENABLED=true +# BAMBUDDY_OIDC_AUTO_CREATE_USERS=false +# BAMBUDDY_OIDC_AUTO_LINK_EXISTING=false +# BAMBUDDY_OIDC_EMAIL_CLAIM=email +# BAMBUDDY_OIDC_REQUIRE_EMAIL_VERIFIED=true +# BAMBUDDY_OIDC_ICON_URL= +# BAMBUDDY_OIDC_AUTOLOGIN=false +# +# Booleans accept true/1/yes; anything else keeps the default. +# +# AUTO_LINK_EXISTING binds an OIDC identity to an existing local account with +# the same email address. With EMAIL_CLAIM=email it is refused unless +# REQUIRE_EMAIL_VERIFIED=true, because an identity provider that does not +# verify addresses would let anyone claim someone else's account. The whole +# config is then skipped and logged; the app still starts.