Merge pull request #2084 from rabbitmq/deprecate-oauth2-settings

4.1: Deprecate two OAuth 2 settings

Author: michaelklishin

docs/management/index.md

@@ -410,8 +410,13 @@ Given above configuration, when a user visits the management UI, the following t
     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
     :::
 
+    :::warning
+    `management.oauth_metadata_url` and `management.oauth_resource_servers.$id.oauth_metadata_url` are deprecated. You should configure the OpenId Discovery endpoint's path as it is explained [here](./oauth2#discovery-endpoint-params). 
+    These two settings will no longer exist in RabbitMQ 4.2.0. In the meantime, RabbitMQ will support them until you update your configuration.
+    :::
+
     :::tip
-    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).
+    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.
@@ -510,29 +515,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 +623,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

@@ -24,15 +24,14 @@ limitations under the License.
 This guide explains how to set up OAuth 2.0 for RabbitMQ
 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 using Entra ID (API version 2.0)
 
 ## Prerequisites to follow this guide
 
-* Have an account in https://portal.azure.com.
+* Have an [Azure account](https://portal.azure.com.)
 * Docker
-* Openssl
-* A local clone of a [GitHub repository](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next) for branch `next` that contains all the configuration files and scripts used on this example.
+* OpenSSL
+* A local clone of a [GitHub repository](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next) (the `next` branch) that contains all the configuration files and scripts used on this example.
 
 ## Register your app
 
@@ -62,12 +61,12 @@ When using **Entra ID as OAuth 2.0 server**, your client app (in our case Rabbit
 
 5. Click on **Register**.
 
-    ![Entra ID OAuth 2.0 App](./entra-id-oauth-registered-app.png)
+   ![Entra ID OAuth 2.0 App](./entra-id-oauth-registered-app.png)
 
-    Note the following values, as you will need it later to configure the `rabbitmq_auth_backend_oauth2` on RabbitMQ side:
+   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,8 +145,24 @@ 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 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:
+
+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}`.
+
+Check out the last section to see how this scope is used to configure RabbitMQ.
+
+## Configure Custom Signing Keys
+
 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
 
@@ -167,18 +182,20 @@ This scope will be used further below in this guide.
 ## Configure Custom Signing Keys
 
 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*.
+In the following example, 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}
+```
+
+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.
 
 ```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.
@@ -193,7 +210,17 @@ Edit the new `rabbitmq.conf` file and proceed as follows:
 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_oauth2.discovery_endpoint_params.appid = {Application(client) ID}
+#...
+
+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}/v2.0
+
+#...
 ```
 
 
@@ -207,7 +234,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

@@ -170,35 +170,31 @@ 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**: 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/next/conf/okta/rabbitmq.conf.tmpl) from the tutorial repository
-to `rabbitmq.conf`. It must be in the same directory as `rabbitmq.conf.tmpl`.
+  - **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**.
 
+Clone [rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next/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/next/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.
+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:
 
@@ -210,21 +206,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

@@ -45,7 +45,7 @@ The guide is accompanied by [a public GitHub repository](https://github.com/rabb
 
 ### 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)
@@ -190,7 +190,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*.