Skip to content

Commit

Permalink
Explain how to configure extra params for authorize and token endpoints
Browse files Browse the repository at this point in the history
  • Loading branch information
MarcialRosales committed Oct 3, 2024
1 parent 2966a6d commit 352acf8
Show file tree
Hide file tree
Showing 9 changed files with 209 additions and 103 deletions.
31 changes: 30 additions & 1 deletion docs/management/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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

Expand Down
28 changes: 21 additions & 7 deletions docs/oauth2-examples-auth0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down
61 changes: 25 additions & 36 deletions docs/oauth2-examples-entra-id/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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)

Expand All @@ -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)

Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/oauth2-examples-multiresource.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 352acf8

Please sign in to comment.