From ef56fac1d50a6c1f428376c2a677636547f868b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= <323649642+oc-tmueller@users.noreply.github.com> Date: Thu, 17 Sep 2026 23:24:42 +0200 Subject: [PATCH] docs: document the OIDC audience parameter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The openidconnect app gains an optional "audience" key naming the value the IdP puts into the access token's "aud" claim. It defaults to client-id, and is needed by IdPs that address the resource server instead - RFC 9068 §3 defines an access token's "aud" that way, and Microsoft ADFS follows it, prefixing the application identifier with "microsoft:identityserver:" unless that identifier is already a URL. Documented for 11.0 and 10.16, the two versions the app change ships on. The entry covers the operational consequences rather than just the syntax, because each of them is a way to lock an instance out: the audience becomes authoritative once set, so a token issued to another client of the same IdP is accepted when its "aud" matches, an introspection response that omits "aud" can no longer be used at all, and with token-exchange mode the first list entry is what gets requested from the IdP. Values that cannot be an audience are discarded, and if none is left every access token is rejected. For finding the ADFS value, both cmdlets are named: Get-AdfsWebApiApplication for an OpenID Connect application group, Get-AdfsRelyingPartyTrust for a legacy WS-Federation or SAML trust. Naming only the latter would strand admins whose OIDC registration is an application group, which is the modern default. No app version numbers are claimed: neither release carrying the fix is tagged yet, so the entry points at the issue instead. See owncloud/openidconnect#373 and owncloud/openidconnect#374 Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Thomas Müller <323649642+oc-tmueller@users.noreply.github.com> --- .../config_apps_sample_php_parameters.adoc | 30 +++++++++++++++++++ .../config_apps_sample_php_parameters.adoc | 30 +++++++++++++++++++ 2 files changed, 60 insertions(+) diff --git a/content/server/10.16/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc b/content/server/10.16/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc index dc12276..8fb8cf9 100644 --- a/content/server/10.16/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc +++ b/content/server/10.16/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc @@ -400,6 +400,36 @@ allowed-user-backends:: Limit the users which are allowed to login to a specific user backend - e.g. LDAP (`'allowed-user-backends' ⇒ ['LDAP']`) +audience:: +The value your IdP puts into the access token's `aud` (audience) claim. Once set, an access +token is accepted only if this names the resource ownCloud is being addressed as. Takes a single +non-empty string or a list of them, and *replaces* `client-id` as the expected value rather +than adding to it. The default is `client-id`, which is what most IdPs send, so set this +only if your IdP names the resource server instead. Microsoft ADFS does: it prefixes the +identifier of the application the token was issued for with `microsoft:identityserver:`, +unless that identifier is already a URL, in which case it is sent verbatim. Read the +identifier with `Get-AdfsWebApiApplication` for an OpenID Connect application group +registration, or with `Get-AdfsRelyingPartyTrust` for a legacy WS-Federation or SAML +relying party trust. It is often configured to the same GUID as the `client-id`, which is +why the prefixed value frequently repeats it - but it is a *resource* identifier, not the +client, and the two are free to differ. Whatever your IdP sends must be reproduced here +exactly, including case: the comparison is strict, so a difference in casing, or a numeric +`aud` against a string here, will not match. ++ +Setting this key makes `aud` authoritative, which has three consequences worth planning for. +A token issued to a *different* client of the same IdP is accepted whenever its `aud` +matches, because the `client_id` of RFC 7662 is no longer consulted - so choose a value that +only ownCloud can be issued for, and do not reuse a tenant-wide resource identifier here. +Do not set the key at all if your token introspection response omits `aud`, which RFC 7662 +permits, because every opaque token would then be rejected. And with +`exchange-token-mode-before-introspection`, the first usable entry of a list is also what the +token exchange requests from the IdP, so list the resource ownCloud should be given first. ++ +Anything that cannot be an audience - a number, a boolean, an empty string, an empty list - +is discarded. If nothing usable is left, every access token is rejected and a warning naming +the offending value is written to the log. Requires the app release carrying the fix for +https://github.com/owncloud/openidconnect/issues/373[openidconnect issue 373]. + auth-params:: Additional parameters which are sent to the IdP during the auth requests diff --git a/content/server/11.0/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc b/content/server/11.0/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc index 56eefb2..458779f 100644 --- a/content/server/11.0/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc +++ b/content/server/11.0/modules/admin_manual/pages/configuration/server/config_apps_sample_php_parameters.adoc @@ -395,6 +395,36 @@ allowed-user-backends:: Limit the users which are allowed to log in to a specific user backend - e.g. LDAP (`'allowed-user-backends' ⇒ ['LDAP']`) +audience:: +The value your IdP puts into the access token's `aud` (audience) claim. Once set, an access +token is accepted only if this names the resource ownCloud is being addressed as. Takes a single +non-empty string or a list of them, and *replaces* `client-id` as the expected value rather +than adding to it. The default is `client-id`, which is what most IdPs send, so set this +only if your IdP names the resource server instead. Microsoft ADFS does: it prefixes the +identifier of the application the token was issued for with `microsoft:identityserver:`, +unless that identifier is already a URL, in which case it is sent verbatim. Read the +identifier with `Get-AdfsWebApiApplication` for an OpenID Connect application group +registration, or with `Get-AdfsRelyingPartyTrust` for a legacy WS-Federation or SAML +relying party trust. It is often configured to the same GUID as the `client-id`, which is +why the prefixed value frequently repeats it - but it is a *resource* identifier, not the +client, and the two are free to differ. Whatever your IdP sends must be reproduced here +exactly, including case: the comparison is strict, so a difference in casing, or a numeric +`aud` against a string here, will not match. ++ +Setting this key makes `aud` authoritative, which has three consequences worth planning for. +A token issued to a *different* client of the same IdP is accepted whenever its `aud` +matches, because the `client_id` of RFC 7662 is no longer consulted - so choose a value that +only ownCloud can be issued for, and do not reuse a tenant-wide resource identifier here. +Do not set the key at all if your token introspection response omits `aud`, which RFC 7662 +permits, because every opaque token would then be rejected. And with +`exchange-token-mode-before-introspection`, the first usable entry of a list is also what the +token exchange requests from the IdP, so list the resource ownCloud should be given first. ++ +Anything that cannot be an audience - a number, a boolean, an empty string, an empty list - +is discarded. If nothing usable is left, every access token is rejected and a warning naming +the offending value is written to the log. Requires the app release carrying the fix for +https://github.com/owncloud/openidconnect/issues/373[openidconnect issue 373]. + auth-params:: Additional parameters, which are sent to the IdP during the auth requests