OAuth 2: edits #2056

Author: michaelklishin

docs/management/index.md

@@ -404,10 +404,10 @@ 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` 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.
+1. RabbitMQ uses the URL found in `auth_oauth2.issuer` to download the OpenID Provider configuration. Learn more in the [OAuth 2.0 guide](./oauth2#discovery-endpoint-params)
 
     :::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.
+    If RabbitMQ cannot download the OpenID provider configuration, it shows an error message and the OAuth 2.0 authentication option will be disabled in the management UI
     :::
 
     :::tip
@@ -510,18 +510,29 @@ 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}
+### Configure Extra URI 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. 
+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.
 
-Here is an example of setting an extra parameter called `audience` for both endpoints, the **authorization** and **token** endpoint:
+In the followingexample an extra URI parameter called `audience` is added for both the **authorization** and **token** endpoints:
 
-```ini 
-management.oauth_authorization_endpoint_params.audience = some-audience-id 
-management.oauth_token_endpoint_params.audience = some-audience-id 
+```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}
 
@@ -618,16 +629,17 @@ the following settings:
 - `resource` : `rabbit_prod`
 - `scopes` : `openid rabbitmq.tag:management rabbitmq.read:*/*`
 
-#### Configure extra parameters for authorization and token endpoints
+### Configure Extra URI 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 and specified per resource. The Management UI already sends all the parameters required by the OAuth 2.0 Authorization Code flow. 
+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.
 
-Here is an example of setting an extra parameter called `audience` for both endpoints for the resource `some-resource-id`:
+The following example sets an extra URI parameter called `audience` for both endpoints for the resource `some-resource-id`:
 
-```ini 
+```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 
+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

@@ -1,5 +1,5 @@
 ---
-title: Use https://auth0.com/ as Auth 2.0 server
+title: Use auth0.com as OAuth 2.0 Server
 displayed_sidebar: docsSidebar
 ---
 <!--
@@ -19,26 +19,26 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# Use https://auth0.com/ as OAuth 2.0 server
+# Use [auth0.com](https://auth0.com) as OAuth 2.0 server
 
 This guide explains how to set up OAuth 2.0 for RabbitMQ
 and Auth0 as Authorization Server using the following flows:
 
 * Access [management UI](./management/) via a browser
-* Access management rest api
+* Access management HTTP API
 * Application authentication and authorization
 
 ## Prerequisites to follow this guide
 
-* Have an account in https://auth0.com/.
+* Have an [Auth0](https://auth0.com/) account
 * Docker
 * 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
 
 ## Create RabbitMQ API
 
 In Auth0, resources are mapped to Application APIs.
 
-1. Once you have logged onto your account in https://auth0.com/, go to **dashboard > Applications > APIs > Create an API**.
+1. After logging into the Auth0 account, go to **dashboard > Applications > APIs > Create an API**.
 2. Give it the name `rabbitmq`. The important thing here is the `identifier` which must have the name of the *resource_server_id* we configured in RabbitMQ. This `identifier` goes into the `audience` JWT field. In our case, it is called `rabbitmq`.
 3. Choose `RS256` as the signing algorithm.
 4. Enable **RBAC**.
@@ -99,7 +99,8 @@ 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
 
-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`).
+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`.
 
 Edit `rabbitmq.conf` and proceed as follows:
 
@@ -108,12 +109,14 @@ Edit `rabbitmq.conf` and proceed as follows:
 
 :::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`.
+Starting with RabbitMQ 4.1.x, you must configure RabbitMQ to include a URI parameter
+called `audience` whose value matches the value of `auth_oauth2.resource_server_id`.
 
-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`.
+Earlier RabbitMQ versions always sent this URI parameter. If this additional URI parameter is not configured,
+Auth0 will consider the token invalid and RabbitMQ will display "No authorized" for error.
+
+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`.
 
 :::
 

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

@@ -49,7 +49,7 @@ When using **Entra ID as OAuth 2.0 server**, your client app (in our case Rabbit
 4. In the **Register an application** pane, provide the following information:
 
     * **Name**: the name you would like to give to your application (ex: *rabbitmq-oauth2*)
-    * **Supported Account Types**: select **Accounts in this organizational directory only (Default Directory only - Single tenant)** (you can choose other options if you want to enlarge the audience of your app)
+    * **Supported Account Types**: select **Accounts in this organizational directory only (Default Directory only - Single tenant)** (this guide will focus on this option for simplicity)
     * On the **Select a platform** drop-down list, select **Single-page application (SPA)**
     * Configure the **Redirect URI** to: `https://localhost:15671/js/oidc-oauth/login-callback.html`
 
@@ -66,8 +66,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
@@ -146,36 +146,45 @@ 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 for management UI
+## Create a Scope for Management UI Access
 
 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:
+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
 
-1. Go to **App registrations**.
-2. Click on your application.
-3. Go to **Manage** option on the left menu and choose the option **Expose an API**.
-4. Click on **Add a scope**.
-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}`.
+Therefore, create a new scope associated with the application registered above to be used for RabbitMQ management UI.
+To do so:
+
+1. Go to **App registrations**
+2. Click on your application
+3. Go to **Manage** option on the left menu and choose the option **Expose an API**
+4. Click on **Add a scope**
+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}`
+
+This scope will be used further below in this guide.
 
-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 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.
+Creating a signing key for the application is optional. If a custom key is created, RabbitMQ must be configured accordingly.
+In the example below, replace `{Application(client) ID}` with the actual *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.
 
 ```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 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`).
+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`.
 
 Edit the new `rabbitmq.conf` file and proceed as follows:
 
@@ -198,7 +207,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` in the previous steps of this tutorial.
+based on the values set in `rabbitmq.conf` in the previous steps of this tutorial.
 
 ## Automatic generation of a TLS Certificate and Key Pair
 

docs/oauth2-examples-keycloak.md

@@ -25,7 +25,7 @@ This guide explains how to set up OAuth 2.0 for RabbitMQ
 and Keycloak as Authorization Server using the following flows:
 
 * Access [management UI](./management/) via a browser
-* Access management rest api
+* Access management HTTP API
 * Application authentication and authorization
 
 ## Prerequisites to follow this guide