feat(vaultwarden): add SSO/OIDC support with Zitadel documentation

- Add SSO environment variables to template.yaml (SSO_ENABLED, SSO_ONLY,
  SSO_AUTHORITY, SSO_CLIENT_ID, SSO_CLIENT_SECRET, SSO_SCOPES, SSO_PKCE,
  SSO_AUDIENCE_TRUSTED)
- Add SSO variables to .env.sample with Zitadel audience quirk explained
- Document full Zitadel setup in README: app creation, redirect URI, OIDC
  settings, and the audience fix (SSO_AUDIENCE_TRUSTED=^\d{18}$)
- Update .gitignore to track .env.sample files in docker-compose-files

.gitignore

@@ -229,6 +229,7 @@ docker-compose-files/**/*
 !docker-compose-files/**/config/**
 !docker-compose-files/**/Dockerfile
 !docker-compose-files/**/README.md
+!docker-compose-files/**/.env.sample
 !docker-compose-files/caddy/Caddyfile_template
 docker-compose-files/caddy/Caddyfile
 

docker-compose-files/vaultwarden/.env.sample

@@ -0,0 +1,36 @@
+# Vaultwarden
+VAULTWARDEN_VERSION=latest
+# Full URL where Vaultwarden is reachable (used for FIDO2/WebAuthn and email links)
+VAULTWARDEN_DOMAIN=https://vaultwarden.home.example.com
+VAULTWARDEN_SIGNUPS_ALLOWED=false
+# Generate with: docker run --rm -it vaultwarden/server /vaultwarden hash
+VAULTWARDEN_ADMIN_TOKEN=
+VAULTWARDEN_PORT=8800
+VAULTWARDEN_BIND_IP=0.0.0.0
+VAULTWARDEN_MEM_LIMIT=256m
+
+# Mobile push notifications (optional — register at https://bitwarden.com/host/)
+VAULTWARDEN_PUSH_ENABLED=false
+VAULTWARDEN_PUSH_ID=
+VAULTWARDEN_PUSH_KEY=
+
+# SSO via OIDC (optional — set SSO_AUTHORITY to enable)
+# See README for Zitadel setup instructions
+VAULTWARDEN_SSO_ENABLED=false
+VAULTWARDEN_SSO_ONLY=false
+VAULTWARDEN_SSO_AUTHORITY=
+VAULTWARDEN_SSO_CLIENT_ID=
+VAULTWARDEN_SSO_CLIENT_SECRET=
+VAULTWARDEN_SSO_SCOPES=openid email profile offline_access
+VAULTWARDEN_SSO_PKCE=true
+# Zitadel includes all project app client IDs in aud; trust any 18-digit Zitadel ID.
+# Adjust the digit count if your Zitadel instance uses a different ID length.
+VAULTWARDEN_SSO_AUDIENCE_TRUSTED=^\d{18}$
+
+# SMTP settings (shared with other stacks — leave blank to disable email)
+EMAIL_HOST=
+EMAIL_PORT=587
+EMAIL_HOST_USER=
+EMAIL_HOST_PASSWORD=
+VAULTWARDEN_SMTP_FROM=
+VAULTWARDEN_SMTP_SECURITY=starttls

docker-compose-files/vaultwarden/README.md

@@ -114,6 +114,58 @@ VAULTWARDEN_SMTP_FROM=vault@example.com
 VAULTWARDEN_SMTP_SECURITY=starttls
 ```
 
+## SSO via OIDC (Zitadel)
+
+Vaultwarden supports single sign-on through any OIDC provider. The steps below
+use Zitadel.
+
+### Zitadel application setup
+
+1. In the Zitadel console, create or select a **Project**.
+2. Inside that project add a new **Application** → type **Web**.
+3. Configure the OIDC settings:
+   - **Response Type**: Code
+   - **Authentication Method**: Basic
+   - **Grant Types**: Authorization Code, Refresh Token
+4. Under **Redirect Settings** add the redirect URI:
+   ```
+   https://vaultwarden.home.example.com/identity/connect/oidc-signin
+   ```
+5. Note the **Client ID** and generate a **Client Secret**.
+
+### Vaultwarden `.env` settings
+
+```dotenv
+VAULTWARDEN_SSO_ENABLED=true
+VAULTWARDEN_SSO_ONLY=true          # set false to keep password login as fallback
+VAULTWARDEN_SSO_AUTHORITY=https://zitadel.example.com
+VAULTWARDEN_SSO_CLIENT_ID=<client-id>
+VAULTWARDEN_SSO_CLIENT_SECRET=<client-secret>
+VAULTWARDEN_SSO_SCOPES=openid email profile offline_access
+VAULTWARDEN_SSO_PKCE=true
+VAULTWARDEN_SSO_AUDIENCE_TRUSTED=^\d{18}$
+```
+
+### Zitadel audience quirk
+
+Zitadel includes the client IDs of **all applications in the same project** in
+the `aud` claim of the ID token, not just the one the user authenticated with.
+Vaultwarden rejects the token if any audience value is not trusted.
+
+`SSO_AUDIENCE_TRUSTED=^\d{18}$` trusts any 18-digit Zitadel ID, which covers
+all app client IDs that may appear in the audience. If your Zitadel instance
+uses a different ID length, adjust the digit count accordingly. You can also
+pin specific IDs: `^id1|id2|id3$`.
+
+The `offline_access` scope is required to obtain a refresh token so that
+Vaultwarden can extend sessions without re-authentication.
+
+### Organisation SSO identifier
+
+When logging in with the Bitwarden client, enter your organisation's **SSO
+identifier** (configured in the Vaultwarden admin panel under
+`/admin/organizations`) when prompted.
+
 ## Backup
 
 Back up the `vaultwarden_data` named volume. It contains the SQLite database,

docker-compose-files/vaultwarden/template.yaml

@@ -20,6 +20,16 @@ services:
       PUSH_ENABLED: "{{VAULTWARDEN_PUSH_ENABLED:-false}}"
       PUSH_INSTALLATION_ID: "{{VAULTWARDEN_PUSH_ID:-}}"
       PUSH_INSTALLATION_KEY: "{{VAULTWARDEN_PUSH_KEY:-}}"
+      # SSO via OIDC (optional — leave SSO_AUTHORITY blank to disable)
+      SSO_ENABLED: "{{VAULTWARDEN_SSO_ENABLED:-false}}"
+      SSO_ONLY: "{{VAULTWARDEN_SSO_ONLY:-false}}"
+      SSO_AUTHORITY: "{{VAULTWARDEN_SSO_AUTHORITY:-}}"
+      SSO_CLIENT_ID: "{{VAULTWARDEN_SSO_CLIENT_ID:-}}"
+      SSO_CLIENT_SECRET: "{{VAULTWARDEN_SSO_CLIENT_SECRET:-}}"
+      SSO_SCOPES: "{{VAULTWARDEN_SSO_SCOPES:-openid email profile offline_access}}"
+      SSO_PKCE: "{{VAULTWARDEN_SSO_PKCE:-true}}"
+      # Zitadel puts all project app client IDs in aud; trust any 18-digit ID
+      SSO_AUDIENCE_TRUSTED: "{{VAULTWARDEN_SSO_AUDIENCE_TRUSTED:-}}"
     volumes:
       - /etc/localtime:/etc/localtime:ro
       - vaultwarden_data:/data