Explain how to configure extra params for authorize and token endpoints

Author: MarcialRosales

docs/management/index.md

@@ -414,6 +414,10 @@ Given above configuration, when a user visits the management UI, the following t
     If you used to configure `management.oauth_metadata_url` because your provider did not use the standard OpenId Discovery endpoint's path, since RabbitMQ 4.1 you should instead configure the correct path as it is explained [here](./oauth2#discovery-endpoint-params).
     :::
 
+    :::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}
@@ -510,29 +514,18 @@ 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 URI Parameters for Authorization and Token Endpoints {#extra-endpoint-params}
+### Configure extra parameters for authorization and token endpoints {#extra-endpoint-params}
 
-Some OAuth 2.0 providers require additional URI parameters to be included into the request sent to the **authorization endpoint** and/or to the **token endpoint**.
-These parameters are vendor- or IDP installation-specific. The Management UI already sends all the parameters required by the OAuth 2.0 Authorization Code flow.
+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.
 
-In the followingexample an extra URI parameter called `audience` is added for both the **authorization** and **token** endpoints:
+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
-```
-
-Multiple parameters can be configured like so:
-
-```ini
-management.oauth_authorization_endpoint_params.audience = some-audience-id
-management.oauth_authorization_endpoint_params.example = example-value
-
 management.oauth_token_endpoint_params.audience = some-audience-id
-management.oauth_token_endpoint_params.other = other-value
 ```
 
+You can configure as many parameters as you need.
 
 ### Special attention to CSP header `connect-src` {#csp-header}
 
@@ -629,12 +622,11 @@ the following settings:
 - `resource` : `rabbit_prod`
 - `scopes` : `openid rabbitmq.tag:management rabbitmq.read:*/*`
 
-### Configure Extra URI Parameters for Authorization and Token Endpoints {#extra-endpoint-params}
+#### Configure extra parameters for authorization and token endpoints
 
-Some OAuth 2.0 providers require additional URI parameters to be included into the request sent to the **authorization endpoint** and/or to the **token endpoint**.
-These parameters are vendor- or IDP installation-specific. The Management UI already sends all the parameters required by the OAuth 2.0 Authorization Code flow.
+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.
 
-The following example sets an extra URI parameter called `audience` for both endpoints for the resource `some-resource-id`:
+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

docs/oauth2-examples-auth0.md

@@ -99,8 +99,7 @@ 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
 
-Copy [conf/auth0/rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/conf/auth0/rabbitmq.conf.tmpl) as `rabbitmq.conf`.
-It must be in same folder as `rabbitmq.conf.tmpl`.
+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:
 

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

@@ -28,22 +28,16 @@ and Microsoft Entra ID as Authorization Server using the following flows:
 * Access the management UI via a browser using v2.0 api version
 
 =======
-* Access the management UI via a browser.
->>>>>>> Modify Entra example so that it uses v2.0
+* Access the management UI via a browser using v2.0 api version
+
+>>>>>>> Explain how to configure extra params for authorize and token endpoints
 
 ## Prerequisites to follow this guide
 
 * Have an account in https://portal.azure.com.
-<<<<<<< HEAD
 * Docker
 * Openssl
 * A local clone of a [GitHub repository](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial) that contains all the configuration files and scripts used on this example
-=======
-* Docker.
-* Openssl.
-* `git clone https://github.com/rabbitmq/rabbitmq-oauth2-tutorial`. This github repository
-contains all the configuration files and scripts used on this example.
->>>>>>> Modify Entra example so that it uses v2.0
 
 ## Register your app
 
@@ -77,13 +71,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:
 
-<<<<<<< HEAD
     * **Directory (tenant ID)**
     * **Application (client) ID**
-=======
-    * Directory (tenant ID)
-    * Application (client) ID
->>>>>>> Modify Entra example so that it uses v2.0
 
 
 ## Create OAuth 2.0 roles for your app
@@ -162,14 +151,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.
 
-<<<<<<< HEAD
-## Create a Scope for Management UI Access
-=======
-## Create scope required by Management ui during authorization
+## Create scope required by Management UI during authorization
 
-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.
@@ -178,10 +164,9 @@ 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
->>>>>>> Modify Entra example so that it uses v2.0
 
 There is one last configuration step required. Without this step, the `access_token` returned
 by **Entra ID** won't be useable with RabbitMQ. More specifically, RabbitMQ will not be able to validate its signature because the `access_token` is meant for Microsoft resources
@@ -208,18 +193,19 @@ In the following example, replace `{Application(client) ID}` with the actual *Ap
 auth_oauth2.discovery_endpoint_params.appid = {Application(client) ID}
 ```
 
-Without this bit of configuration, the standard `jwks_uri` endpoint will not include the custom signing key
-and therefore RabbitMQ will not find the necessary 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 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).
+```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.
 
-Clone [rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/entra/rabbitmq.conf.tmpl) from the tutorial repository
-to `rabbitmq.conf`. It must be in the same directory as `rabbitmq.conf.tmpl`.
+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`).
 
 Edit the new `rabbitmq.conf` file and proceed as follows:
 
@@ -241,6 +227,7 @@ auth_oauth2.issuer = https://login.microsoftonline.com/{Directory (tenant) ID}/v
 #...
 ```
 
+
 ## Start RabbitMQ
 
 Run the following commands to run RabbitMQ docker image:
@@ -251,7 +238,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 values set in `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-okta.md

@@ -171,35 +171,29 @@ Once you've added the user to the appropriate groups and apps, they should have
 
 This step is necessary otherwise the tokens do not carry any of the scopes granted to the users.
 
-1. [Create an access policy](https://developer.okta.com/docs/guides/customize-authz-server/main/#create-access-policies)
-2. [Create a rule](https://developer.okta.com/docs/guides/customize-authz-server/main/#create-rules-for-each-access-policy) for the access policy
+1. Create access policy following these [instructions](https://developer.okta.com/docs/guides/customize-authz-server/main/#create-access-policies).
+2. Create rule for the access policy following these [instructions](https://developer.okta.com/docs/guides/customize-authz-server/main/#create-rules-for-each-access-policy).
 
-## [Optional] Test the Tokens Issued by Okta
+## [Optional] Test the tokens issued by Okta
 
-This step is optional but highly recommended.
+This is totally optional but it can save you time.
 
-1. Go to the **default Authorization Server**
-2. Click on **Token Preview** tab
-3. Fill in all the fields. For **grant type** choose `Authorization Code`
-4. Click on **Preview Token** button
-5. Check the claim `role` to see if it contains the roles assigned earlier in this guide
+1. Go to the **default Authorization Server**.
+2. Click on **Token Preview** tab.
+3. Fill in all the fields. For **grant type** choose `Authorization Code`.
+4. Click on **Preview Token** button.
+5. Check the claim `role` to see if it contains the roles you assigned to your user.
 
 
 ## Configure RabbitMQ to use Okta as OAuth 2.0 Authentication Backend
 
-The configuration on the Okta side is done. Next, configure RabbitMQ to use the resources created above.
+The configuration on Okta side is done. You now have to configure RabbitMQ to use the resources you just created. You took note of the following values:
 
-For that, you will need the following values from the previous steps:
+  - **okta_client_app_ID** associated to the okta app that you registered in okta for rabbitMQ.
+  - **okta-Issuer** associated to the **default Authorization server**.
+  - **okta-Metadata-URI** associated to the **default Authorization server**.
 
-* **okta_client_app_ID**: the ID of the app registered in Okta to be used with RabbitMQ
-* **okta-Issuer**: the **default Authorization server**
-* **okta-Metadata-URI**: the **default Authorization server**
-
-Copy [rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/rabbitmq.conf.tmpl) from the tutorial repository
-to `rabbitmq.conf`. It must be in the same directory as `rabbitmq.conf.tmpl`.
-
-There is a second configuration file, [advanced.config](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/advanced.config),
-that will not need any modifications. This is the RabbitMQ [advanced configuration file](./configure/) where RabbitMQ scopes are mapped to the permissions previously configured in Okta.
+Clone [rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/rabbitmq.conf.tmpl) as `rabbitmq.conf` (in the same folder as `rabbitmq.conf.tmpl`). There is a second configuration file, [advanced.config](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/advanced.config), that you keep it as it is. This is the RabbitMQ advanced configuration that maps RabbitMQ scopes to the permissions previously configured in Okta.
 
 Edit `rabbitmq.conf` and proceed as follows:
 
@@ -211,21 +205,14 @@ or `{okta-issuer}/.well-known/openid-configuration`
 `auth_oauth2.discovery_endpoint_path` accordingly. For instance, if **okta-Metadata-URI** is `{okta-issuer}/some-other-endpoint`, you update `auth_oauth2.discovery_endpoint_path` with the value `some-other-endpoint`.
 
 
-### About the OpenId Discovery Endpoint
-
-RabbitMQ uses the standard OpenId discovery endpoint path `.well-known/openid-configuration`. Okta supports this path in addition to `.well-known/oauth-authorization-server`.
-The only difference observed between the two endpoints is that the latter returns more values in the `claims_supported` JSON field.
+### About OpenId Discovery Endpoint
 
-The RabbitMQ's template configuration provided in the snippet below has this line.
-This means that RabbitMQ will use the standard path.
+RabbitMQ uses the standard OpenId discovery endpoint path `.well-known/openid-configuration`. Okta supports this path in addition to `.well-known/oauth-authorization-server`. The only difference observed at the time of writing this guide is that the latter returns more values in the json attribute `claims_supported`.
 
-If the default does not work as expected, try uncommenting this line to use
-the alternative path.
-
-``` ini
-## Uncomment to use '.well-known/oauth-authorization-server' as the discovery
-## endpoint path
-# auth_oauth2.discovery_endpoint_path = .well-known/oauth-authorization-server
+The RabbitMQ's template configuration provided in this example has this line commented out meaning that
+RabbitMQ will use the standard path. If you find any problems, try uncommenting this line.
+```
+#auth_oauth2.discovery_endpoint_path = .well-known/oauth-authorization-server
 ```
 
 ## Start RabbitMQ

docs/oauth2-examples/index.md

@@ -46,7 +46,7 @@ which hosts all the scripts required to deploy the examples demonstrated on the
 
 ### Using [JWT tokens in several protocols](#access-other-protocols) to access RabbitMQ
 
-* [Management HTTP API](#management-http-api)
+* [Management REST API](#management-rest-api)
 * [AMQP 0-9-1](#amqp-protocol) (and [scopes for topic exchanges](#using-topic-exchanges) in a separate section)
 * [AMQP 1.0](#amqp10-protocol)
 * [JMS](#jms-clients)
@@ -192,7 +192,7 @@ It is only when the user clicks **Click here to login** , the user is redirected
 
 The following subsections demonstrate how to use access tokens with any messaging protocol and also to access the management HTTP API.
 
-### Management HTTP API {#management-http-api}
+### Management REST api {#management-rest-api}
 
 In this scenario a monitoring agent uses RabbitMQ HTTP API to collect monitoring information.
 Because it is not an end user, or human, you refer to it as a *service account*.