Explain how to configure extra params for authorize and token endpoints

Author: MarcialRosales

docs/management/index.md

@@ -375,6 +375,7 @@ To configure OAuth 2.0 in the management UI you need a [minimum configuration](#
     * [Allow Basic and OAuth 2 authentication for management HTTP API](#allow-basic-auth-for-http-api)
     * [Allow Basic and OAuth 2 authentication for management UI](#allow-basic-auth-for-mgt-ui)
     * [Logging out of the management UI](#about-logout-workflow)
+    * [Configure extra parameters for authorization and token endpoints](#extra-endpoint-params)
     * [Special attention to CSP header `connect-src`](#csp-header)
     * [Identity-Provider initiated logon](#idp-initiated-logon)
     * [Support multiple OAuth 2.0 resources](#support-multiple-resources)
@@ -403,12 +404,16 @@ management.oauth_scopes = <SPACE-SEPARATED LIST OF SCOPES. See below>
 - `oauth_scopes` is a mandatory field which must be set at all times except in the case when OAuth providers automatically grant scopes associated to the `oauth_client_id`. `oauth_scopes` is a list of space-separated strings that indicate which permissions the application is requesting. Most OAuth providers only issue tokens with the scopes requested during the user authentication. RabbitMQ sends this field along with its `oauth_client_id` during the user authentication. If this field is not set, RabbitMQ defaults to `openid profile`.
 
 Given above configuration, when a user visits the management UI, the following two events take place:
-1. RabbitMQ uses the URL found in `auth_oauth2.issuer` followed by the path `/.well-known/openid-configuration` to download the OpenID Provider configuration. It contains information about other endpoints such as the `jwks_uri` (used to download the keys to validate the token's signature) or the `token_endpoint`.
+1. RabbitMQ uses the URL found in `auth_oauth2.issuer` to download the OpenID Provider configuration. Check out the [OAuth 2.0](./oauth2#discovery-endpoint-params) documentation about OpenId discovery endpoint to learn more about it.
 
     :::warning
     If RabbitMQ cannot download the OpenID provider configuration, it shows an error message and OAuth 2.0 authentication is disabled in the management UI.
     :::
 
+    :::tip
+    If you used to configure `auth_oauth2.metadata_url` because your provider used a slightly different OpenId Discovery endpoint url, since RabbitMQ 4.1 you should instead configure the correct path and/or include any additional parameters. Please read [this section of the documentation](./oauth2#discovery-endpoint-params) where it is explained how to do it. `auth_oauth2.metadata_url` may be deprecated in future versions.
+    :::
+
 2. RabbitMQ displays a button with the label "Click here to login". When the user clicks on the button, the management UI initiates the OAuth 2.0 Authorization Code Flow, which redirects the user to the identity provider to authenticate and get a token.
 
 ### Configure client secret {#configure-client-secret}
@@ -505,6 +510,19 @@ RabbitMQ 3.13.1 and earlier versions require the [OpenId Connect Discovery endpo
 There are other two additional scenarios which can trigger a logout. One scenario occurs when the OAuth Token expires. Although RabbitMQ renews the token in the background before it expires, if the token expires, the user is logged out.
 The second scenario is when the management UI session exceeds the maximum allowed time configured on the [Login Session Timeout](#login-session-timeout).
 
+### Configure extra parameters for authorization and token endpoints {#extra-endpoint-params}
+
+There are some OAuth 2.0 providers which require extra parameters in the request sent to the **authorization endpoint** and/or to the **token endpoint**. These parameters are custom parameters. The Management UI already sends all the parameters required by the OAuth 2.0 Authorization Code flow. 
+
+Here is an example of setting an extra parameter called `audience` for both endpoints, the **authorization** and **token** endpoint:
+
+```ini 
+management.oauth_authorization_endpoint_params.audience = some-audience-id 
+management.oauth_token_endpoint_params.audience = some-audience-id 
+```
+
+You can configure as many parameters as you need. 
+
 ### Special attention to CSP header `connect-src` {#csp-header}
 
 To support the OAuth 2.0 protocol, RabbitMQ makes asynchronous REST calls to the [OpenId Connect Discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). If you override the default [CSP headers](#csp), you have to make sure that the `connect-src` CSP directive whitelists the [OpenId Connect Discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest).
@@ -600,6 +618,17 @@ the following settings:
 - `resource` : `rabbit_prod`
 - `scopes` : `openid rabbitmq.tag:management rabbitmq.read:*/*`
 
+#### Configure extra parameters for authorization and token endpoints
+
+There are some OAuth 2.0 providers which require extra parameters in the request sent to the **authorization endpoint** and/or to the **token endpoint**. These parameters are custom parameters and specified per resource. The Management UI already sends all the parameters required by the OAuth 2.0 Authorization Code flow. 
+
+Here is an example of setting an extra parameter called `audience` for both endpoints for the resource `some-resource-id`:
+
+```ini 
+management.oauth_resource_servers.2.id = some-resource-id
+management.oauth_resource_servers.2.oauth_authorization_endpoint_params.audience = some-resource-id 
+management.oauth_resource_servers.2.oauth_token_endpoint_params.audience = some-resource-id 
+```
 
 #### Optionally do not expose some resources in the management UI
 

docs/oauth2-examples-auth0.md

@@ -70,10 +70,9 @@ of the end user.
 In the settings, choose:
 
 * Application type : `Single Page applications`
-* Token Endpoint Authentication Method:  `None`
-* Allowed Callback URLs: `http://localhost:15672/js/oidc-oauth/login-callback.html`
-* Allowed Web Origins: `http://localhost:15672`
-* Allowed Origins (CORS): `http://localhost:15672`
+* Allowed Callback URLs: `https://localhost:15671/js/oidc-oauth/login-callback.html`
+* Allowed Web Origins: `https://localhost:15671`
+* Allowed Origins (CORS): `https://localhost:15671`
 
 
 ## Create a User for Management UI Access
@@ -101,8 +100,23 @@ To configure RabbitMQ you need to gather the following information from Auth0:
 4. And take note of the *Domain* value
 5. Use the last values in *Client ID* and *Domain* fields in the RabbitMQ configuration file
 
-Edit the configuration file [conf/auth0/rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/conf/auth0/rabbitmq.conf) and replace `{CLIENT_ID}` and `{DOMAIN}` with the
-values you gathered above.
+Clone the configuration file [conf/auth0/rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/conf/auth0/rabbitmq.conf.tmpl) as `rabbitmq.conf` (in the same folder as `rabbitmq.conf.tmpl`).
+
+Edit `rabbitmq.conf` and proceed as follows:
+
+1. Replace `{Client ID}` with the values you gathered above.
+2. Same for `{Domain}`
+
+:::important
+
+Since RabbitMQ 4.1.x, you must configure RabbitMQ to include a request parameter
+called `audience` whose value matches the value you set in `auth_oauth2.resource_server_id`.
+Earlier RabbitMQ versions always sent this parameter. If you do not configure it,
+Auth0 sends an invalid token and RabbitMQ shows the error message `No authorized`.
+
+These [two configuration lines](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/conf/auth0/rabbitmq.conf.tmpl#L8-L9) configure the `audience` parameter with the value `rabbitmq`.
+
+:::
 
 ## Start RabbitMQ
 
@@ -115,7 +129,7 @@ make start-rabbitmq
 
 ## Verify Management UI flows
 
-1. Go to management UI `http://localhost:15672`.
+1. Go to management UI `https://localhost:15671`.
 2. Click on the single button, authenticate with your secondary Auth0 user. You should be redirected back to the management UI.
 
 **Auth0** issues an access token like this one below. It has in the `scope` claim

docs/oauth2-examples-entra-id/index.md

@@ -24,7 +24,8 @@ limitations under the License.
 Demonstrate how to authenticate using the OAuth 2.0 protocol
 and Microsoft Entra ID as Authorization Server using the following flows:
 
-* Access the management UI via a browser.
+* Access the management UI via a browser using v2.0 api version
+
 
 ## Prerequisites to follow this guide
 
@@ -66,8 +67,8 @@ When using **Entra ID as OAuth 2.0 server**, your client app (in our case Rabbit
 
     Note the following values, as you will need it later to configure the `rabbitmq_auth_backend_oauth2` on RabbitMQ side:
 
-    * Directory (tenant ID)
-    * Application (client) ID
+    * **Directory (tenant ID)**.
+    * **Application (client) ID**.
 
 
 ## Create OAuth 2.0 roles for your app
@@ -90,18 +91,12 @@ To learn more about roles in Entra ID, see [Entra ID documentation](https://docs
 
 2. Then, click on **Create App Role** to create an OAuth 2.0 role that will be used to give access to the RabbitMQ Management UI.
 
-:::info
-
-To learn more about how permissions are managed when RabbitMQ is used together with OAuth 2.0,
-see [this portion of the OAuth 2 tutorial](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial#about-permissions)
-
-:::
 
 3. On the right menu that has just opened, provide the requested information:
 
     * **Display Name**: the name you want to give to the role (ex: *Management UI Admin*)
     * **Allowed member types**: Both (Users/Groups + Applications)
-    * **Value**: `Application_ID.tag:administrator` (where *Application_ID* is the value of the *Application (client) ID* noted earlier in this tutorial)
+    * **Value**: `{Application_ID}.tag:administrator` (where *Application_ID* is the value of the *Application (client) ID* noted earlier in this tutorial)
     * **Description**: briefly describe what this role aims to (here just to give admin access to the RabbitMQ Management UI)
     * **Do you want to enable this app role**: `yes` (check the box)
 
@@ -115,7 +110,7 @@ see [this portion of the OAuth 2 tutorial](https://github.com/rabbitmq/rabbitmq-
 
     * **Display Name**: the name you want to give to the role (ex: *Configure All Vhosts*)
     * **Allowed member types**: Both (Users/Groups + Applications)
-    * **Value**: `Application_ID.configure:*/*` (where *Application_ID* is the value of the *Application (client) ID* noted earlier in this tutorial)
+    * **Value**: `{Application_ID}.configure:*/*` (where *Application_ID* is the value of the *Application (client) ID* noted earlier in this tutorial)
     * **Description**: briefly describe what this role aims to (here to give permissions to configure all resources on all the vhosts available on the RabbitMQ instance)
     * **Do you want to enable this app role**: `yes` (check the box)
 
@@ -152,11 +147,11 @@ Now that some roles have been created for your application, you still need to as
 
 9. Repeat the operations for all the roles you want to assign.
 
-## Create scope required by Management ui during authorization
+## Create scope for management UI
 
-So far we have created the roles and granted the roles to the user who is going to
-access the management UI. When this user logs into RabbitMQ management UI, its token
-contains the granted roles.
+There is one last configuration step required. Without this step, the `access_token` returned
+by **Entra ID** is invalid. RabbitMQ cannot validate its signature because the `access_token` is meant for Microsoft resources.
+First, you need to create a scope associated to the application you registered for RabbitMQ management UI as follows:
 
 1. Go to **App registrations**.
 2. Click on your application.
@@ -165,40 +160,35 @@ contains the granted roles.
 5. Enter a name, eg. `management-ui`. Enter the same name for **Admin consent display name** and a description and save it.
 7. The scope is named `api://{Application (client) ID}/{scope_name}`.
 
-RabbitMQ management ui must provide this scope in `management.oauth_scopes` along with `openid profiles` scopes.
+Check out the last section to see how this scope is used to configure RabbitMQ.
 
 ## Configure Custom Signing Keys
 
-It is optional to create a signing key for your application. If you create one though, you must append an `appid` query parameter containing the *app ID* to the `jwks_uri`. Otherwise, the standard jwks_uri endpoint will not include the custom signing key and RabbitMQ will not find the signing key to validate the token's signature.
+It is optional to create a signing key for your application. If you create one though, you must add the following RabbitMQ configuration. You need to replace `{Application(client) ID}` with your *Application(client) ID*. Without this configuration, the standard jwks_uri endpoint will not include the custom signing key and RabbitMQ will not find the signing key to validate the token's signature.
 
-For example, given your application id, `{my-app-id}` and your tenant `{tenant}`, the OIDC discovery endpoint uri would be `https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid={my-app-id}`. The returned payload contains the `jwks_uri` attribute whose value is something like `https://login.microsoftonline.com/{tenant}/discovery/keys?appid=<my-app-idp>`. RabbitMQ should be configured with that `jwks_uri` value.
+```ini
+auth_oauth2.discovery_endpoint_params.appid = {Application(client) ID}
+```
 
+For more information, check out Microsoft Entra documentation about [configuring custom signing keys](https://learn.microsoft.com/en-us/entra/identity-platform/jwt-claims-customization#validate-token-signing-key).
 
 ## Configure RabbitMQ to Use Entra ID as OAuth 2.0 Authentication Backend
 
-The configuration on Entra ID side is done. Next, configure RabbitMQ to use these resources.
+The configuration on **Entra ID** side is done. Next, configure RabbitMQ to use these resources.
 
-[rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/entra/rabbitmq.conf) is a sample RabbitMQ configuration to **enable Entra ID as OAuth 2.0 authentication backend** for the RabbitMQ Management UI.
+Clone the file called [rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/entra/rabbitmq.conf.tmpl) as `rabbitmq.conf` (in the same folder as `rabbitmq.conf.tmpl`).
 
-Update it with the following values:
+Edit the new `rabbitmq.conf` file and proceed as follows:
 
-* **Tenant ID** associated to the app that you registered in Entra ID
-* **Application ID** associated to the app that you registered in Entra ID
-* Value of the **jwks_uri** key from `https://login.microsoftonline.com/{TENANT_ID}/v2.0/.well-known/openid-configuration`
+1. Replace `{Directory (tenant) ID}` with the value gathered earlier as **Application (client) ID**
+2. Replace `{Application(client) ID}` with the value gathered as **Application (client) ID**
+3. If you decide to configure your application with custom signing(s), you need to uncomment the following configuration line. This is required otherwise the `jwks_uri` endpoint announced by the OpenID Discovery endpoint does not contain applications' custom signing keys.
 
 ```ini
-auth_backends.1 = rabbit_auth_backend_oauth2
-
-management.oauth_enabled = true
-management.oauth_client_id = {Application(client) ID}
-management.oauth_scopes = openid profile api://{Application(client) ID}/rabbitmq
-
-auth_oauth2.resource_server_id = {Application(client) ID}
-auth_oauth2.additional_scopes_key = roles
-auth_oauth2.issuer = https://login.microsoftonline.com/{Directory (tenant) ID}
-
+#auth_oauth2.discovery_endpoint_params.appid = {Application(client) ID}
 ```
 
+
 ## Start RabbitMQ
 
 Run the following commands to run RabbitMQ docker image:
@@ -209,8 +199,7 @@ make start-rabbitmq
 ```
 
 This starts a Docker container named `rabbitmq`, with RabbitMQ Management UI/API with HTTPS enabled, and configured to use your Entra ID as OAuth 2.0 authentication backend,
-based on the information you provided in [rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/conf/entra/rabbitmq.conf)
-in the previous steps of this tutorial.
+based on the information you provided in `rabbitmq.conf` in the previous steps of this tutorial.
 
 ## Automatic generation of a TLS Certificate and Key Pair
 

docs/oauth2-examples-multiresource.md

@@ -66,7 +66,7 @@ This is a summary of the configuration, found in [rabbitmq.conf](https://github.
     auth_oauth2.preferred_username_claims.1 = preferred_username
     auth_oauth2.preferred_username_claims.2 = user_name
     auth_oauth2.preferred_username_claims.3 = email
-    auth_oauth2.jwks_url = https://keycloak:8443/realms/test/protocol/openid-connect/certs
+    auth_oauth2.issuer = https://keycloak:8443/realms/test
     auth_oauth2.scope_prefix = rabbitmq.
     auth_oauth2.https.peer_verification = verify_peer
     auth_oauth2.https.cacertfile = /etc/rabbitmq/keycloak-cacert.pem