First doc changes due to PR 10012 on rabbitmq-server

site/oauth2.md

@@ -262,7 +262,7 @@ auth_oauth2.scope_prefix = api://
 
 ### <a id="multiple-resource-servers" class="anchor" href="#multiple-resource-servers">Multiple Resource Server(s)</a>
 
-Typically, all users that access a RabbitMQ installation are registered in the same Identity Provider. Furthermore, all tokens issued for the same RabbitMQ installation have the same *audience*.
+Typically, all users that access a RabbitMQ cluster are registered within the same Identity Provider. And likewise, all tokens targeting the same RabbitMQ cluster also carry the same *audience*. In other words, all users reference a RabbitMQ cluster with the same name, a.k.a. *audience* using OAuth 2.0 terminology.
 
 However, there are some use-cases where RabbitMQ is either accessed by users registered in different Identity Providers or tokens issued for the same RabbitMQ installation use different *Audience*(s). For these use-cases, RabbitMQ OAuth 2.0 plugin and the Management plugin can be configured with multiple OAuth 2.0 resources.
 
@@ -277,13 +277,18 @@ auth_oauth2.resource_servers.2.id = rabbit_dev
 auth_oauth2.resource_servers.2.scope_prefix = dev-rabbitmq.
 </pre>
 
-All `auth_oauth2` settings such as `jwks_url`, `scope_prefix` are still supported when configuring multiple resources. Their values are used as default values. For instance, `rabbit_prod` takes its `scope_prefix` from `auth_oauth2.scope_prefix`. However, `rabbit_dev` configures its own `scope_prefix`.
+Not all `auth_oauth2` settings are supported to configure individual resource servers. These are the supported
+attributes:
+- `id` - This is the actual resource identifier carried in the `audience` field of a token. If omitted, the value is the index, e.g. given `auth_oauth2.resource_servers.prod.scope_prefix` setting, the `id` would be `prod`.
+- `scope_prefix`
+- `additional_scopes_key`
+- `resource_server_type`
+- `oauth_provider_id` - This is the identifier of the OAuth provider, configured in RabbitMQ, which provides all the settings to contact the Authorization server in order to retrieve the signing keys to validate the token. If this setting is omitted, RabbitMQ looks up the default Authorization Provider's id in the
+setting `auth_oauth2.default_oauth_provider`. And if it is also omitted, RabbitMQ uses `auth_oauth2.issuer` or `auth_oauth2.jwks_url` to download the signings keys to validate the token.
 
-Once RabbitMQ sees one resource configured under `auth_oauth2.resource_servers`, it ignores `auth_oauth2.resource_server_id` if present.
+The list of supported resources by a RabbitMQ cluster is the combination of `auth_oauth2.resource_servers` and `auth_oauth2.resource_server_id` if any of them is present.
 
-**NOTE**: It is possible to configure `jwks_url` on each individual resource via the `auth_oauth2.resource_servers.$.jwks_url` setting, however it is not possible to configure the signing key files except under `auth_oauth2.signing_keys`.
-
-**NOTE**: There is an [example](./oauth2-examples-multiresource.html) that demonstrate multiple OAuth 2 resources. 
+**NOTE**: There is an [example](./oauth2-examples-multiresource.html) that demonstrate multiple OAuth 2 resources.
 
 ### <a id="token-validation" class="anchor" href="#token-validation">Token validation</a>