docs: document the OIDC audience parameter - #137

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) <noreply@anthropic.com>
Signed-off-by: Thomas Müller <323649642+oc-tmueller@users.noreply.github.com>

The audience parameter alone does not tell an admin whether they need it, and for
one supported provider it cannot help at all: Keycloak sends no aud claim unless an
audience mapper is configured, so no configured value can ever match. openidconnect
2.4.2 and 2.3.5 therefore also accept the claim naming the client a token was issued
to - azp, appid or client_id - and that is what these pages now describe.

- oidc.adoc gains an "Access Token Audience" section. Because the behaviour differs
  per app version and both fixing releases are still unreleased, the applicability
  is structural rather than a footnote: the table has one column per version - "On
  2.4.1" and "On 2.4.2" for ownCloud 11, "On 2.3.4 and earlier" and "On 2.3.5" for
  ownCloud 10 - so a reader of any single row sees what applies to the version they
  actually run. On 2.4.1 that means Keycloak needs the audience mapper, Azure needs
  requestedAccessTokenVersion 2, and ADFS and OneLogin have no remedy short of the
  upgrade. The section also covers both log lines an admin will meet, the refusal of
  tokens marked as refresh tokens, the deliberate exception for ID tokens, and the
  Keycloak audience-mapper recipe with its console path and kcadm.sh command.

- config_apps_sample_php_parameters.adoc: the audience entry described the default
  as "the client-id", which is only half of it, and ended in a placeholder instead
  of a version. Both fixed, with the versions marked as in preparation since neither
  2.4.2 nor 2.3.5 is tagged.

- ms-azure-setup.adoc: requestedAccessTokenVersion decides whether aud holds the
  Application ID URI (v1.0 tokens, the default) or the client id (v2.0). On
  openidconnect 2.4.1 that decides whether the documented setup works at all, which
  this walkthrough never said.

Each table row records whether it was observed or taken from vendor documentation;
PingFederate and cidaas are marked undetermined rather than guessed, and the
ownCloud 10 page says so where it would otherwise promise that no upgrade can lock a
provider out.

Two review rounds folded in. The claims that a token issued to a different client is
"rejected either way" and that "an attacker's own client cannot get a token through
either check" were both wrong and both contradicted elsewhere in the same section:
the audience comparison cannot tell which client asked for a token that names
ownCloud. The recommendation to set audience *because* another client might target
ownCloud was inverted for the same reason - in that scenario the key changes nothing
and removes the client-claim check; it binds the resource, not the client, and the
pages now say which of the two they mean. Also: the Keycloak workaround was
addressed to ownCloud 10 admins who cannot run 2.4.1 at all; the Azure snippet used
the client-id placeholder where the App ID URI belongs, which would have rejected
every token once audience was set; and the Azure manifest path read Manifest > Manage
instead of Manage > Manifest.A third round corrected the ID-token statement, which claimed to hold "independently
of the audience". It does not: with audience set to anything other than the client-id -
what ADFS, Azure v1.0 and OneLogin need - an ID token's aud no longer matches and the
client-claim fallback is suppressed, so ID tokens are rejected. That is a real benefit
of the key and the pages now list it. Also in that round: the ownCloud 11 entry's lead
described 2.4.2 behaviour in the present tense while 2.4.1 is what ships; the Keycloak
2.4.2 cell said audience "cannot be used" without allowing for an install that followed
the 2.4.1 instruction and added the mapper; OneLogin was missing from the admonition
that lists who is affected; the Azure note called the suppressed claim "the appid
fallback" where v2.0 tokens use azp; and neither page said that on 2.4.1 the check
reaches JWT access tokens only, so an install using opaque tokens with introspection is
not affected at all.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Thomas Müller <323649642+oc-tmueller@users.noreply.github.com>

…iting them

config_apps_sample_php_parameters.adoc is generated from core's
config/config.apps.sample.php by owncloud/config-to-docs, which the audience entry on
this branch did not account for: it existed only here, so the next regeneration would
have deleted it. The text now lives in core - one commit per server line - and these
two pages are that generator's output.

Confirmed before regenerating that both pages were byte-identical to what the
generator produces from their respective core branches, so this diff is exactly the
new entries and nothing else, and running the generator again is a no-op.

Five keys arrive with it that the app has always read and neither page documented:
exchange-token-mode-before-introspection,
use-access-token-introspection-for-user-info, and the three ocis-routing-policy-*
keys.

The audience entry is shortened in the move, from ten paragraphs to five. A config
sample entry is read in the PHP file as well as in the manual, and the long-form
discussion belongs in the hand-written Access Token Audience section, which this
entry now links to per server version. Two things it had picked up are gone from
here: the refresh-token rule, which is not a property of this key, and the ID-token
consequence stated twice. Corrections from review, all verified against the app code:
the 11.0 text says the 2.4.1 lockout applies to JWT access tokens (2.4.1 does not
check the audience on the introspection path at all), the 10.16 text no longer claims
the upgrade cannot lock anyone out (an introspection response with neither "aud" nor
"client_id" is rejected), and the client-claim acceptance is version-qualified inline
rather than only in the closing paragraph.

oidc.adoc and ms-azure-setup.adoc are hand-authored pages and are untouched here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Thomas Müller <323649642+oc-tmueller@users.noreply.github.com>