Merge pull request #2056 from rabbitmq/switch-to-entra-id-v2

(Mostly) 4.1: Document optional OAuth 2.0 settings required for each identity provider

Author: michaelklishin

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,10 +404,14 @@ 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. 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
+    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).
     :::
 
 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.
@@ -505,6 +510,30 @@ 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}
+
+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.
+
+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
+```
+
+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
+```
+
+
 ### 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 +629,18 @@ 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}
+
+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.
+
+The following example sets an extra URI 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

@@ -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**.
@@ -69,10 +69,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
@@ -100,8 +99,26 @@ 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.
+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:
+
+1. Replace `{Client ID}` with the values you gathered above.
+2. Same for `{Domain}`
+
+:::important
+
+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`.
+
+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`.
+
+:::
 
 ## Start RabbitMQ
 
@@ -114,7 +131,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.
 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
+* Access the management UI via a browser using v2.0 api version
+
 
 ## Prerequisites to follow this guide
 
@@ -48,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`
 
@@ -65,16 +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
-
-6. Click on the **Endpoints** tab if it is visible.
-7. On the right pane that has just opened, copy the value of **OpenID Connect metadata document** (ex: `https://login.microsoftonline.com/{TENANT_ID}/v2.0/.well-known/openid-configuration`) and open it in your browser.
-
-    Note the value of the `jwks_uri` key (ex: `https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys`), as you will also need it later to configure the `rabbitmq_auth_backend_oauth2` on RabbitMQ side.
-
-    ![Entra ID JWKS URI](./entra-id-jwks-uri.png)
-8. If the **Endpoints** tab is not visible,
+    * **Directory (tenant ID)**
+    * **Application (client) ID**
 
 
 ## Create OAuth 2.0 roles for your app
@@ -97,18 +90,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)
 
@@ -122,7 +109,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)
 
@@ -159,38 +146,57 @@ 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.
 
-## Configure Custom Signing Keys
+## Create a Scope for Management UI Access
 
-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.
+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
 
-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.
+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}`
 
-## Configure RabbitMQ to Use Entra ID as OAuth 2.0 Authentication Backend
+This scope will be used further below in this guide.
 
-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.
+## Configure Custom Signing Keys
 
-Update it with the following values:
+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*.
 
-* **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`
+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_backends.1 = rabbit_auth_backend_oauth2
-auth_backends.2 = rabbit_auth_backend_internal
+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
 
-management.oauth_enabled = true
-management.oauth_client_id = {PUT YOUR AZURE AD APPLICATION ID}
-management.oauth_provider_url = https://login.microsoftonline.com/{YOUR_ENTRA_ID_TENANT_ID}
+The configuration on **Entra ID** side is done. Next, configure RabbitMQ to use these resources.
 
-auth_oauth2.resource_server_id = {PUT YOUR AZURE AD APPLICATION ID}
-auth_oauth2.additional_scopes_key = roles
-auth_oauth2.jwks_url = {PUT YOUR ENTRA ID JWKS URI VALUE}
+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:
+
+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_oauth2.discovery_endpoint_params.appid = {Application(client) ID}
 ```
 
+
 ## Start RabbitMQ
 
 Run the following commands to run RabbitMQ docker image:
@@ -201,8 +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](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/conf/entra/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

docs/oauth2-examples-multiresource.md

@@ -67,6 +67,7 @@ The RabbitMQ OAuth 2 plugin is configured like so:
     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.issuer = https://keycloak:8443/realms/test
     auth_oauth2.scope_prefix = rabbitmq.
     ```
     * With one oauth provider: