From 11549b2b0c626b56c81e8ac945fc83e15d9a99c2 Mon Sep 17 00:00:00 2001
From: Stefan Hausotte <stefan.hausotte@gmx.de>
Date: Tue, 1 Sep 2026 18:50:03 +0200
Subject: [PATCH] docs: document the OAuth2 additional audiences setting

Add `additional_audiences` to the OAuth2/OIDC config values and describe
when it is needed: providers such as Zitadel issue ID tokens whose `aud`
claim lists more than the client ID, which Kellnr rejects by default.

Cover the two points a reader trips over: the configured client ID must
still appear in `aud`, and the environment variable takes a
comma-separated list.
---
 src/views/DocumentationV6View.vue | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/views/DocumentationV6View.vue b/src/views/DocumentationV6View.vue
index 7920276..82f6dff 100644
--- a/src/views/DocumentationV6View.vue
+++ b/src/views/DocumentationV6View.vue
@@ -869,6 +869,9 @@ const mobileNavOpen = ref(false);
                 default-value="" description="OAuth2 client ID from your identity provider." />
               <ConfigCard title="Client Secret" toml="[oauth2] client_secret" env-var="KELLNR_OAUTH2__CLIENT_SECRET"
                 default-value="" description="OAuth2 client secret. Recommended to set via environment variable." />
+              <ConfigCard title="Additional Audiences" toml="[oauth2] additional_audiences"
+                env-var="KELLNR_OAUTH2__ADDITIONAL_AUDIENCES" default-value="[]"
+                description="Audiences accepted in the ID token besides the client ID, which stays required." />
               <ConfigCard title="Scopes" toml="[oauth2] scopes" env-var="KELLNR_OAUTH2__SCOPES"
                 default-value='["openid", "profile", "email"]'
                 description="OAuth2 scopes to request from the identity provider." />
@@ -985,6 +988,26 @@ const mobileNavOpen = ref(false);
               </ol>
             </TextBlock>
 
+            <TextBlock>
+              <b>Multiple Audiences</b><br />
+              Some identity providers, Zitadel among them, issue ID tokens whose <i>aud</i> claim lists several
+              audiences instead of the client ID alone. Kellnr rejects an audience it does not know, because every
+              audience named in a token is able to present that token to Kellnr. If your provider adds further
+              audiences, list the ones you trust:
+            </TextBlock>
+
+            <CodeBlock lang="toml">
+              [oauth2]
+              additional_audiences = ["other-client-id", "project-id"]
+            </CodeBlock>
+
+            <TextBlock>
+              The configured <i>client_id</i> still has to appear in the <i>aud</i> claim. The allowlist covers only
+              the additional entries, and leaving it empty, the default, keeps every additional audience rejected.
+              As an environment variable the list is comma-separated:
+              <i>KELLNR_OAUTH2__ADDITIONAL_AUDIENCES=other-client-id,project-id</i>.
+            </TextBlock>
+
             <TextBlock>
               <b>User Provisioning</b><br />
               When <i>auto_provision_users</i> is enabled (default), Kellnr automatically creates a local user account