diff --git a/docs/management/index.md b/docs/management/index.md index 17ada2ed9..e2d7a8da8 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -404,10 +404,10 @@ management.oauth_scopes = - `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 diff --git a/docs/oauth2-examples-auth0.md b/docs/oauth2-examples-auth0.md index aeaa7e862..f0269c982 100644 --- a/docs/oauth2-examples-auth0.md +++ b/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 --- -# 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 @@ -38,7 +38,7 @@ and Auth0 as Authorization Server using the following flows: 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`. ::: diff --git a/docs/oauth2-examples-entra-id/index.md b/docs/oauth2-examples-entra-id/index.md index dd1287a9b..8026c2fc5 100644 --- a/docs/oauth2-examples-entra-id/index.md +++ b/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,24 +146,31 @@ 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} @@ -171,11 +178,13 @@ 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 diff --git a/docs/oauth2-examples-keycloak.md b/docs/oauth2-examples-keycloak.md index 12fd9982a..b982b331d 100644 --- a/docs/oauth2-examples-keycloak.md +++ b/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 diff --git a/docs/oauth2-examples-okta.md b/docs/oauth2-examples-okta.md index 68556b069..cb3046054 100644 --- a/docs/oauth2-examples-okta.md +++ b/docs/oauth2-examples-okta.md @@ -63,7 +63,7 @@ In Trusted Origins (for Web and Native app integrations), choose **keep the defa In Assignments, choose **Allow everyone in your organization to access**. -:::tip +:::warning Deactivate `Federation Broker Mode`. Our testing suggests that if the `Federation Broker Mode` was activated (this is what Okta recommends), it would not possible to assign this application to groups and users. @@ -73,7 +73,7 @@ it would not possible to assign this application to groups and users. Finally, prepare to copy and save a value that will be displayed on one of the following screens, then click on **Save**. -:::tip +:::important After clicking **Save**, take note of the following values, the will be necessary later to configure RabbitMQ: @@ -171,34 +171,35 @@ 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 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). +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 -## [Optional] Test the tokens issued by Okta +## [Optional] Test the Tokens Issued by Okta -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 you assigned to your user. +This step is optional but highly recommended. +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 ## Configure RabbitMQ to use Okta as OAuth 2.0 Authentication Backend -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: +The configuration on the Okta side is done. Next, configure RabbitMQ to use the resources created above. + +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`). +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. +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. Edit `rabbitmq.conf` and proceed as follows: @@ -210,14 +211,21 @@ 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 OpenId Discovery 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 at the time of writing this guide is that the latter returns more values in the json attribute `claims_supported`. +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. -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 +The RabbitMQ's template configuration provided in the snippet below has this line. +This means that RabbitMQ will use the standard path. + +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 ``` ## Start RabbitMQ diff --git a/docs/oauth2-examples/index.md b/docs/oauth2-examples/index.md index 561489d25..980dc7e07 100644 --- a/docs/oauth2-examples/index.md +++ b/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 REST API](#management-rest-api) +* [Management HTTP API](#management-http-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,9 +190,9 @@ It is only when the user clicks **Click here to login** , the user is redirected ## Using JWT tokens in several protocols to access RabbitMQ {#access-other-protocols} -The following subsections demonstrate how to use access tokens with any messaging protocol and also to access the management rest api. +The following subsections demonstrate how to use access tokens with any messaging protocol and also to access the management HTTP API. -### Management REST api {#management-rest-api} +### Management HTTP API {#management-http-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*. @@ -786,9 +786,9 @@ make start-rabbitmq **NOTE**: You do not need to run any OAuth 2.0 server like UAA. This is because you are creating a token and signing it using the same private-public key pair RabbitMQ is configured with. -*Use a Rich Authorization Token to access the management rest api* +*Use a Rich Authorization Token to access the management HTTP API* -You are going use this token [jwts/rar-token.json](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/jwts/rar-token.json) to access an endpoint of the management rest api. +You are going use this token [jwts/rar-token.json](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/jwts/rar-token.json) to access an endpoint of the Management HTTP API. ```bash make curl-with-token URL=http://localhost:15672/api/overview TOKEN=$(bin/jwt_token rar-token.json legacy-token-key private.pem public.pem) diff --git a/docs/oauth2.md b/docs/oauth2.md index dff0ff4e3..24f4c540f 100644 --- a/docs/oauth2.md +++ b/docs/oauth2.md @@ -108,7 +108,9 @@ Also, the `https://my-oauth2-provider.com/realm/rabbitmq/.well-known/openid-conf *.well-known/openid-configuration* is the OpenID standard path for the OpenID Provider Configuration endpoint ::: -If your provider exposes a different path and/or requires some extra http parameters for the OpenId discovery endpoint, you can configure them as follows: +If the Identity Provider used exposes a different path and/or requires adding some extra URI parameters for the OpenID discovery endpoint, +they can be configured as follows: + ```ini auth_oauth2.discovery_endpoint_path = my/custom/path auth_oauth2.discovery_endpoint_params.appid = some-app-id @@ -122,10 +124,10 @@ This plugin does not communicate with any OAuth 2.0 provider in order to authent Tokens must be digitally signed otherwise they are not accepted. RabbitMQ must have the signing key to validate the signature. You can either configure the signing keys the OAuth 2.0 provider will use, or configure RabbitMQ with one of the following two endpoints: - - **JWKS endpoint** - this is the HTTP endpoint that returns the signing keys used to digitally sign the tokens. - - **OpenID Provider Configuration endpoint** - this is the endpoint that returns the provider's configuration including all its endpoints, such as the **JWKS endpoint**. +* **JWKS endpoint**: this is the HTTP endpoint that returns the signing keys used to digitally sign the tokens +* **OpenID Provider Configuration endpoint**: this endpoint returns the provider's configuration including all of its endpoints, most importantly the **JWKS endpoint** -When you configure RabbitMQ with one of two previous endpoints, RabbitMQ must make a HTTP request (or two, if you specify the latter endpoint) to download the signing keys. This is an operation that occurs once for any signing key not downloaded yet. When the OAuth 2.0 provider rotates the signing keys, newer tokens refer to a new signing key which RabbitMQ does not have yet which triggers another download of the newer signing keys. +When RabbitMQ is configured with one of two previous endpoints, RabbitMQ must make a HTTP request (or two, if you specify the latter endpoint) to download the signing keys. This is an operation that occurs once for any signing key not downloaded yet. When the OAuth 2.0 provider rotates the signing keys, newer tokens refer to a new signing key which RabbitMQ does not have yet which triggers another download of the newer signing keys. The token can be any [JWT token](https://jwt.io/introduction/) which contains the `scope` and `aud` fields. @@ -144,27 +146,27 @@ In chronological order, here is the sequence of events that occur when a client |--------------------------------------------|----------- | `auth_oauth2.resource_server_id` | The [Resource Server ID](#resource-server-id) | `auth_oauth2.resource_server_type` | The Resource Server Type required when using [Rich Authorization Request](#rich-authorization-request) token format -| `auth_oauth2.additional_scopes_key` | Configure the plugin to look for scopes in other fields (maps to `additional_rabbitmq_scopes` in the old format). | -| `auth_oauth2.scope_prefix` | [Configure the prefix for all scopes](#scope-prefix). The default value is `auth_oauth2.resource_server_id` followed by the dot `.` character. | -| `auth_oauth2.preferred_username_claims` | [List of the JWT claims](#preferred-username-claims) to look for the username associated with the token. -| `auth_oauth2.default_key` | ID of the default signing key. -| `auth_oauth2.signing_keys` | Paths to the [signing key files](#signing-key-files). -| `auth_oauth2.issuer` | The [issuer URL](#configure-issuer) of the authorization server. It is used to build the discovery endpoint url to discover other endpoints such as such as `jwks_uri`. And this issuer URL is also the URL where to send RabbitMQ management users to login and get a token. +| `auth_oauth2.additional_scopes_key` | Configure the plugin to look for scopes in other fields (maps to `additional_rabbitmq_scopes` in the old format) | +| `auth_oauth2.scope_prefix` | [Configure the prefix for all scopes](#scope-prefix). The default value is `auth_oauth2.resource_server_id` followed by the dot `.` character | +| `auth_oauth2.preferred_username_claims` | [List of the JWT claims](#preferred-username-claims) to look for the username associated with the token +| `auth_oauth2.default_key` | ID of the default signing key +| `auth_oauth2.signing_keys` | Paths to the [signing key files](#signing-key-files) +| `auth_oauth2.issuer` | The [issuer URL](#configure-issuer) of the authorization server. Used to build the discovery endpoint URL to discover other endpoints such as such as `jwks_uri`. Management UI users will be sent to this for logging in | `auth_oauth2.discovery_endpoint_path` | The path used for the [OpenId discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). The endpoint URI is built using `auth_oauth2.issuer`, this path or else the default path `.well-known/openid-configuration` followed by query parameters configured in the following variable -| `auth_oauth2.discovery_endpoint_params` | [List of HTTP query parameters](#discovery-endpoint-params) sent to the OpenId discovery endpoint. -| `auth_oauth2.jwks_url` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must be https. Optional if you set `auth_oauth2.issuer`. If this URL is set, it overrides the `jwks_uri` discovered via the discovery endpoint. -| `auth_oauth2.token_endpoint` | The URL of the OAuth 2.0 token endpoint. Optional if you set `auth_oauth2.issuer`. If this URL is set, it overrides the `token_endpoint` discovered via the discovery endpoint. -| `auth_oauth2.https.cacertfile` | Path to a file containing PEM-encoded CA certificates. The CA certificates are used to connect to any of these endpoints: `jwks_url`, `token_endpoint`, or the discovery endpoint. -| `auth_oauth2.https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10. +| `auth_oauth2.discovery_endpoint_params` | [List of HTTP query parameters](#discovery-endpoint-params) sent to the OpenId discovery endpoint +| `auth_oauth2.jwks_url` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must use "https" for schema. Optional if you set `auth_oauth2.issuer`. If this URL is set, it overrides the `jwks_uri` discovered via the discovery endpoint +| `auth_oauth2.token_endpoint` | The URL of the OAuth 2.0 token endpoint. Optional if you set `auth_oauth2.issuer`. If this URL is set, it overrides the `token_endpoint` discovered via the discovery endpoint +| `auth_oauth2.https.cacertfile` | Path to a file containing PEM-encoded CA certificates. The CA certificates are used to connect to any of these endpoints: `jwks_url`, `token_endpoint`, or the discovery endpoint +| `auth_oauth2.https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10 | `auth_oauth2.https.peer_verification` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set.

**Deprecated**: This variable will be soon replaced by `auth_oauth2.https.verify`. Users should stop using this variable. -| `auth_oauth2.https.fail_if_no_peer_cert` | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false`. -| `auth_oauth2.https.hostname_verification` | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none`. -| `auth_oauth2.https.crl_check` | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false. -| `auth_oauth2.algorithms` | Restrict [the usable algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support). -| `auth_oauth2.verify_aud` | Whether to verify the [token's `aud`](#token-validation) field or not. The default value is `true`. -| `auth_oauth2.resource_servers` | [Multiple OAuth 2.0 resources configuration](#multiple-resource-servers-configuration). -| `auth_oauth2.oauth_providers` | [Multiple OAuth 2.0 providers configuration](#multiple-oauth-providers-configuration). -| `auth_oauth2.default_oauth_provider` | ID of the OAuth 2.0 provider used for the `auth_oauth2.resource_servers`, that did not specify any (via the variable `oauth_provider_id`) or when `auth_oauth2.jwks_url` and `auth_oauth2.issuer` are both missing. +| `auth_oauth2.https.fail_if_no_peer_cert` | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false` +| `auth_oauth2.https.hostname_verification` | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none` +| `auth_oauth2.https.crl_check` | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false +| `auth_oauth2.algorithms` | Restrict [the usable algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support) +| `auth_oauth2.verify_aud` | Whether to verify the [token's `aud`](#token-validation) field or not. The default value is `true` +| `auth_oauth2.resource_servers` | [Multiple OAuth 2.0 resources configuration](#multiple-resource-servers-configuration) +| `auth_oauth2.oauth_providers` | [Multiple OAuth 2.0 providers configuration](#multiple-oauth-providers-configuration) +| `auth_oauth2.default_oauth_provider` | ID of the OAuth 2.0 provider used for the `auth_oauth2.resource_servers`, that did not specify any (via the variable `oauth_provider_id`) or when `auth_oauth2.jwks_url` and `auth_oauth2.issuer` are both missing #### Resource Server ID {#resource-server-id} @@ -268,7 +270,7 @@ Each `auth_oauth2.oauth_providers.{id/index}` entry has the following sub-keys. | `discovery_endpoint_path` | The path used for the OpenId discovery endpoint. Default value is `.well-known/openid-configuration` | `discovery_endpoint_params` | [List of HTTP query parameters](#discovery-endpoint-params) sent to the OpenId discovery endpoint. | `token_endpoint` | The URL of the OAuth 2.0 token endpoint. Optional if you configured `issuer`. -| `jwks_uri` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must be https.

**Warning**: RabbitMQ uses for each OAuth Provider the variable name `jwks_uri` used by the OpenId Connect Discovery Specification rather than `jwks_url`. This variable is optional if you set `issuer`. +| `jwks_uri` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must use "https" for schema.

**Warning**: RabbitMQ uses for each OAuth Provider the variable name `jwks_uri` used by the OpenId Connect Discovery Specification rather than `jwks_url`. This variable is optional if you set `issuer`. | `https.cacertfile` | Path to a file containing PEM-encoded CA certificates used to connect `issuer` and/or `jwks_uri` URLs. | `https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10. | `https.verify` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set. @@ -412,7 +414,7 @@ the `monitoring` tag will be `my_rabbit.tag:monitoring`. ### Configure OAuth 2.0 provider's issuer {#configure-issuer} -Before RabbitMQ 3.13, users had to either configure the JWKS endpoint (that is `auth_oauth2.jwks_url` variable) or statically [configure the signing keys](#configure-signing-keys). Now, users only need to configure the OpenID Provider's **issuer** URL and from this URL RabbitMQ downloads the OpenID Provider configuration which includes the JWKS endpoint in addition to other endpoints which will be useful in other contexts. +Before RabbitMQ 3.13, users had to either configure the JWKS endpoint (that is `auth_oauth2.jwks_url` variable) or statically [configure the signing keys](#configure-signing-keys). Now, users only need to configure the OpenID Provider's **issuer** URL and from this URL RabbitMQ downloads the OpenID Provider configuration which includes the JWKS endpoint in addition to other endpoints which will be useful in other contexts. Usually, this **issuer** URL is the same URL configured in the management plugin (`management.oauth_provider_url`). From now on, you only need to configure a single URL, specified by the `auth_oauth2.issuer` variable. Except in edge cases where the **issuer** URL does not host the login page. In those cases, the user configures the login page in the `management.oauth_provider_url` variable. diff --git a/versioned_docs/version-3.13/management/index.md b/versioned_docs/version-3.13/management/index.md index 9ac3ef844..1e04df207 100644 --- a/versioned_docs/version-3.13/management/index.md +++ b/versioned_docs/version-3.13/management/index.md @@ -406,7 +406,7 @@ Given above configuration, when a user visits the management UI, the following t 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`. :::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 ::: 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. diff --git a/versioned_docs/version-3.13/oauth2-examples-auth0.md b/versioned_docs/version-3.13/oauth2-examples-auth0.md index d3ae7bae4..d1b708035 100644 --- a/versioned_docs/version-3.13/oauth2-examples-auth0.md +++ b/versioned_docs/version-3.13/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 --- -# 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 @@ -38,7 +38,7 @@ and Auth0 as Authorization Server using the following flows: 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**. diff --git a/versioned_docs/version-3.13/oauth2-examples-entra-id/index.md b/versioned_docs/version-3.13/oauth2-examples-entra-id/index.md index f737efdb4..9ffec54cc 100644 --- a/versioned_docs/version-3.13/oauth2-examples-entra-id/index.md +++ b/versioned_docs/version-3.13/oauth2-examples-entra-id/index.md @@ -48,7 +48,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` diff --git a/versioned_docs/version-3.13/oauth2-examples-keycloak.md b/versioned_docs/version-3.13/oauth2-examples-keycloak.md index 12fd9982a..b982b331d 100644 --- a/versioned_docs/version-3.13/oauth2-examples-keycloak.md +++ b/versioned_docs/version-3.13/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 diff --git a/versioned_docs/version-3.13/oauth2-examples/index.md b/versioned_docs/version-3.13/oauth2-examples/index.md index 919a7a626..6af703ee3 100644 --- a/versioned_docs/version-3.13/oauth2-examples/index.md +++ b/versioned_docs/version-3.13/oauth2-examples/index.md @@ -190,9 +190,9 @@ It is only when the user clicks **Click here to login** , the user is redirected ## Access other protocols using OAuth 2.0 tokens {#access-other-protocols} -The following subsections demonstrate how to use access tokens with any messaging protocol and also to access the management rest api. +The following subsections demonstrate how to use access tokens with any messaging protocol and also to access the management HTTP API. -### Management REST api {#management-ui} +### Management HTTP API {#management-ui} 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*. @@ -792,9 +792,9 @@ make start-rabbitmq **NOTE**: You do not need to run any OAuth 2.0 server like UAA. This is because you are creating a token and signing it using the same private-public key pair RabbitMQ is configured with. -*Use a Rich Authorization Token to access the management rest api* +*Use a Rich Authorization Token to access the management HTTP API* -You are going use this token [jwts/rar-token.json](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/jwts/rar-token.json) to access an endpoint of the management rest api. +You are going use this token [jwts/rar-token.json](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/jwts/rar-token.json) to access an endpoint of the Management HTTP API. ```bash make curl-with-token URL=http://localhost:15672/api/overview TOKEN=$(bin/jwt_token rar-token.json legacy-token-key private.pem public.pem) diff --git a/versioned_docs/version-3.13/oauth2.md b/versioned_docs/version-3.13/oauth2.md index 002b6f0b9..71471f12d 100644 --- a/versioned_docs/version-3.13/oauth2.md +++ b/versioned_docs/version-3.13/oauth2.md @@ -115,8 +115,8 @@ This plugin does not communicate with any OAuth 2.0 provider in order to authent Tokens must be digitally signed otherwise they are not accepted. RabbitMQ must have the signing key to validate the signature. You can either configure the signing keys the OAuth 2.0 provider will use, or configure RabbitMQ with one of the following two endpoints: - - **JWKS endpoint** - this is the HTTP endpoint that returns the signing keys used to digitally sign the tokens. - - **OpenID Provider Configuration endpoint** - this is the endpoint that returns the provider's configuration including all its endpoints, such as the **JWKS endpoint**. +* **JWKS endpoint**: this is the HTTP endpoint that returns the signing keys used to digitally sign the tokens. +* **OpenID Provider Configuration endpoint**: this endpoint returns the provider's configuration including all of its endpoints, most importantly the **JWKS endpoint** When you configure RabbitMQ with one of two previous endpoints, RabbitMQ must make a HTTP request (or two, if we specify the latter endpoint) to download the signing keys. This is an operation that occurs once for any signing key not downloaded yet. When the OAuth 2.0 provider rotates the signing keys, newer tokens refer to a new signing key which RabbitMQ does not have yet which triggers another download of the newer signing keys. @@ -137,25 +137,25 @@ In chronological order, here is the sequence of events that occur when a client |--------------------------------------------|----------- | `auth_oauth2.resource_server_id` | The [Resource Server ID](#resource-server-id) | `auth_oauth2.resource_server_type` | The Resource Server Type required when using [Rich Authorization Request](#rich-authorization-request) token format -| `auth_oauth2.additional_scopes_key` | Configure the plugin to look for scopes in other fields (maps to `additional_rabbitmq_scopes` in the old format). | -| `auth_oauth2.scope_prefix` | [Configure the prefix for all scopes](#scope-prefix). The default value is `auth_oauth2.resource_server_id` followed by the dot `.` character. | -| `auth_oauth2.preferred_username_claims` | [List of the JWT claims](#preferred-username-claims) to look for the username associated with the token. -| `auth_oauth2.default_key` | ID of the default signing key. -| `auth_oauth2.signing_keys` | Paths to the [signing key files](#signing-key-files). -| `auth_oauth2.issuer` | The [issuer URL](#configure-issuer) of the authorization server. It is used to build the discovery endpoint url to discover other endpoints such as such as `jwks_uri`. And this issuer URL is also the URL where to send RabbitMQ management users to login and get a token. -| `auth_oauth2.jwks_url` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must be https. -| `auth_oauth2.token_endpoint` | The URL of the OAuth 2.0 token endpoint. -| `auth_oauth2.https.cacertfile` | Path to a file containing PEM-encoded CA certificates. The CA certificates are used to connect to any of these endpoints: `jwks_url`, `token_endpoint`, or the `issuer`. -| `auth_oauth2.https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10. -| `auth_oauth2.https.peer_verification` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set.

**Deprecated**: This variable will be soon replaced by `auth_oauth2.https.verify`. Users should stop using this variable. -| `auth_oauth2.https.fail_if_no_peer_cert` | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false`. -| `auth_oauth2.https.hostname_verification` | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none`. -| `auth_oauth2.https.crl_check` | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false. -| `auth_oauth2.algorithms` | Restrict [the usable algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support). -| `auth_oauth2.verify_aud` | Whether to verify the [token's `aud`](#token-validation) field or not. The default value is `true`. -| `auth_oauth2.resource_servers` | [Multiple OAuth 2.0 resources configuration](#multiple-resource-servers-configuration). -| `auth_oauth2.oauth_providers` | [Multiple OAuth 2.0 providers configuration](#multiple-oauth-providers-configuration). -| `auth_oauth2.default_oauth_provider` | ID of the OAuth 2.0 provider used for the `auth_oauth2.resource_servers`, that did not specify any (via the variable `oauth_provider_id`) or when `auth_oauth2.jwks_url` and `auth_oauth2.issuer` are both missing. +| `auth_oauth2.additional_scopes_key` | Configure the plugin to look for scopes in other fields (maps to `additional_rabbitmq_scopes` in the old format) | +| `auth_oauth2.scope_prefix` | [Configure the prefix for all scopes](#scope-prefix). The default value is `auth_oauth2.resource_server_id` followed by the dot `.` character | +| `auth_oauth2.preferred_username_claims` | [List of the JWT claims](#preferred-username-claims) to look for the username associated with the token +| `auth_oauth2.default_key` | ID of the default signing key +| `auth_oauth2.signing_keys` | Paths to the [signing key files](#signing-key-files) +| `auth_oauth2.issuer` | The [issuer URL](#configure-issuer) of the authorization server. Used to build the discovery endpoint URL to discover other endpoints such as such as `jwks_uri`. Management UI users will be sent to this for logging in +| `auth_oauth2.jwks_url` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must use "https" for schema +| `auth_oauth2.token_endpoint` | The URL of the OAuth 2.0 token endpoint +| `auth_oauth2.https.cacertfile` | Path to a file containing PEM-encoded CA certificates. The CA certificates are used to connect to any of these endpoints: `jwks_url`, `token_endpoint`, or the `issuer` +| `auth_oauth2.https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10 +| `auth_oauth2.https.peer_verification` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set.

**Deprecated**: This variable will be soon replaced by `auth_oauth2.https.verify`. Users should stop using this variable +| `auth_oauth2.https.fail_if_no_peer_cert` | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false` +| `auth_oauth2.https.hostname_verification` | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none` +| `auth_oauth2.https.crl_check` | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false +| `auth_oauth2.algorithms` | Restrict [the usable algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support) +| `auth_oauth2.verify_aud` | Whether to verify the [token's `aud`](#token-validation) field or not. The default value is `true` +| `auth_oauth2.resource_servers` | [Multiple OAuth 2.0 resources configuration](#multiple-resource-servers-configuration) +| `auth_oauth2.oauth_providers` | [Multiple OAuth 2.0 providers configuration](#multiple-oauth-providers-configuration) +| `auth_oauth2.default_oauth_provider` | ID of the OAuth 2.0 provider used for the `auth_oauth2.resource_servers`, that did not specify any (via the variable `oauth_provider_id`) or when `auth_oauth2.jwks_url` and `auth_oauth2.issuer` are both missing #### Resource Server ID {#resource-server-id} @@ -247,7 +247,7 @@ Each `auth_oauth2.oauth_providers..` entry has the following variables |------------------------------|----------- | `issuer` | URL of OAuth Provider. RabbitMQ uses this URL to build the OpenId Connect Discovery endpoint by appending the path `.well-known/openid-configuration` to this URL | `token_endpoint` | The URL of the OAuth 2.0 token endpoint. -| `jwks_uri` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must be https.

**Warning**: RabbitMQ uses for each OAuth Provider the variable name `jwks_uri` used by the OpenId Connect Discovery Specification rather than `jwks_url`. +| `jwks_uri` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must use "https" for schema.

**Warning**: RabbitMQ uses for each OAuth Provider the variable name `jwks_uri` used by the OpenId Connect Discovery Specification rather than `jwks_url`. | `https.cacertfile` | Path to a file containing PEM-encoded CA certificates used to connect `issuer` and/or `jwks_uri` URLs | `https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10. | `https.verify` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set. diff --git a/versioned_docs/version-4.0/management/index.md b/versioned_docs/version-4.0/management/index.md index 9ac3ef844..1e04df207 100644 --- a/versioned_docs/version-4.0/management/index.md +++ b/versioned_docs/version-4.0/management/index.md @@ -406,7 +406,7 @@ Given above configuration, when a user visits the management UI, the following t 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`. :::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 ::: 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. diff --git a/versioned_docs/version-4.0/oauth2-examples-auth0.md b/versioned_docs/version-4.0/oauth2-examples-auth0.md index d3ae7bae4..d1b708035 100644 --- a/versioned_docs/version-4.0/oauth2-examples-auth0.md +++ b/versioned_docs/version-4.0/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 --- -# 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 @@ -38,7 +38,7 @@ and Auth0 as Authorization Server using the following flows: 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**. diff --git a/versioned_docs/version-4.0/oauth2-examples-entra-id/index.md b/versioned_docs/version-4.0/oauth2-examples-entra-id/index.md index f737efdb4..9ffec54cc 100644 --- a/versioned_docs/version-4.0/oauth2-examples-entra-id/index.md +++ b/versioned_docs/version-4.0/oauth2-examples-entra-id/index.md @@ -48,7 +48,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` diff --git a/versioned_docs/version-4.0/oauth2-examples-keycloak.md b/versioned_docs/version-4.0/oauth2-examples-keycloak.md index 12fd9982a..b982b331d 100644 --- a/versioned_docs/version-4.0/oauth2-examples-keycloak.md +++ b/versioned_docs/version-4.0/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 diff --git a/versioned_docs/version-4.0/oauth2-examples/index.md b/versioned_docs/version-4.0/oauth2-examples/index.md index 9cab50979..8e625dc25 100644 --- a/versioned_docs/version-4.0/oauth2-examples/index.md +++ b/versioned_docs/version-4.0/oauth2-examples/index.md @@ -190,9 +190,9 @@ It is only when the user clicks **Click here to login** , the user is redirected ## Access other protocols using OAuth 2.0 tokens {#access-other-protocols} -The following subsections demonstrate how to use access tokens with any messaging protocol and also to access the management rest api. +The following subsections demonstrate how to use access tokens with any messaging protocol and also to access the management HTTP API. -### Management REST api {#management-ui} +### Management HTTP API {#management-ui} 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*. @@ -792,9 +792,9 @@ make start-rabbitmq **NOTE**: You do not need to run any OAuth 2.0 server like UAA. This is because you are creating a token and signing it using the same private-public key pair RabbitMQ is configured with. -*Use a Rich Authorization Token to access the management rest api* +*Use a Rich Authorization Token to access the management HTTP API* -You are going use this token [jwts/rar-token.json](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/jwts/rar-token.json) to access an endpoint of the management rest api. +You are going use this token [jwts/rar-token.json](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/jwts/rar-token.json) to access an endpoint of the Management HTTP API. ```bash make curl-with-token URL=http://localhost:15672/api/overview TOKEN=$(bin/jwt_token rar-token.json legacy-token-key private.pem public.pem) diff --git a/versioned_docs/version-4.0/oauth2.md b/versioned_docs/version-4.0/oauth2.md index 26b978a98..a971f3f63 100644 --- a/versioned_docs/version-4.0/oauth2.md +++ b/versioned_docs/version-4.0/oauth2.md @@ -115,8 +115,8 @@ This plugin does not communicate with any OAuth 2.0 provider in order to authent Tokens must be digitally signed otherwise they are not accepted. RabbitMQ must have the signing key to validate the signature. You can either configure the signing keys the OAuth 2.0 provider will use, or configure RabbitMQ with one of the following two endpoints: - - **JWKS endpoint** - this is the HTTP endpoint that returns the signing keys used to digitally sign the tokens. - - **OpenID Provider Configuration endpoint** - this is the endpoint that returns the provider's configuration including all its endpoints, such as the **JWKS endpoint**. +* **JWKS endpoint**: this is the HTTP endpoint that returns the signing keys used to digitally sign the tokens. +* **OpenID Provider Configuration endpoint**: this endpoint returns the provider's configuration including all of its endpoints, most importantly the **JWKS endpoint** When you configure RabbitMQ with one of two previous endpoints, RabbitMQ must make a HTTP request (or two, if we specify the latter endpoint) to download the signing keys. This is an operation that occurs once for any signing key not downloaded yet. When the OAuth 2.0 provider rotates the signing keys, newer tokens refer to a new signing key which RabbitMQ does not have yet which triggers another download of the newer signing keys. @@ -137,25 +137,25 @@ In chronological order, here is the sequence of events that occur when a client |--------------------------------------------|----------- | `auth_oauth2.resource_server_id` | The [Resource Server ID](#resource-server-id) | `auth_oauth2.resource_server_type` | The Resource Server Type required when using [Rich Authorization Request](#rich-authorization-request) token format -| `auth_oauth2.additional_scopes_key` | Configure the plugin to look for scopes in other fields (maps to `additional_rabbitmq_scopes` in the old format). | -| `auth_oauth2.scope_prefix` | [Configure the prefix for all scopes](#scope-prefix). The default value is `auth_oauth2.resource_server_id` followed by the dot `.` character. | -| `auth_oauth2.preferred_username_claims` | [List of the JWT claims](#preferred-username-claims) to look for the username associated with the token. -| `auth_oauth2.default_key` | ID of the default signing key. -| `auth_oauth2.signing_keys` | Paths to the [signing key files](#signing-key-files). -| `auth_oauth2.issuer` | The [issuer URL](#configure-issuer) of the authorization server. It is used to build the discovery endpoint url to discover other endpoints such as such as `jwks_uri`. And this issuer URL is also the URL where to send RabbitMQ management users to login and get a token. -| `auth_oauth2.jwks_url` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must be https. -| `auth_oauth2.token_endpoint` | The URL of the OAuth 2.0 token endpoint. -| `auth_oauth2.https.cacertfile` | Path to a file containing PEM-encoded CA certificates. The CA certificates are used to connect to any of these endpoints: `jwks_url`, `token_endpoint`, or the `issuer`. -| `auth_oauth2.https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10. -| `auth_oauth2.https.peer_verification` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set.

**Deprecated**: This variable will be soon replaced by `auth_oauth2.https.verify`. Users should stop using this variable. -| `auth_oauth2.https.fail_if_no_peer_cert` | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false`. -| `auth_oauth2.https.hostname_verification` | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none`. -| `auth_oauth2.https.crl_check` | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false. -| `auth_oauth2.algorithms` | Restrict [the usable algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support). -| `auth_oauth2.verify_aud` | Whether to verify the [token's `aud`](#token-validation) field or not. The default value is `true`. -| `auth_oauth2.resource_servers` | [Multiple OAuth 2.0 resources configuration](#multiple-resource-servers-configuration). -| `auth_oauth2.oauth_providers` | [Multiple OAuth 2.0 providers configuration](#multiple-oauth-providers-configuration). -| `auth_oauth2.default_oauth_provider` | ID of the OAuth 2.0 provider used for the `auth_oauth2.resource_servers`, that did not specify any (via the variable `oauth_provider_id`) or when `auth_oauth2.jwks_url` and `auth_oauth2.issuer` are both missing. +| `auth_oauth2.additional_scopes_key` | Configure the plugin to look for scopes in other fields (maps to `additional_rabbitmq_scopes` in the old format) | +| `auth_oauth2.scope_prefix` | [Configure the prefix for all scopes](#scope-prefix). The default value is `auth_oauth2.resource_server_id` followed by the dot `.` character | +| `auth_oauth2.preferred_username_claims` | [List of the JWT claims](#preferred-username-claims) to look for the username associated with the token +| `auth_oauth2.default_key` | ID of the default signing key +| `auth_oauth2.signing_keys` | Paths to the [signing key files](#signing-key-files) +| `auth_oauth2.issuer` | The [issuer URL](#configure-issuer) of the authorization server. Used to build the discovery endpoint URL to discover other endpoints such as such as `jwks_uri`. Management UI users will be sent to this for logging in +| `auth_oauth2.jwks_url` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must use "https" for schema +| `auth_oauth2.token_endpoint` | The URL of the OAuth 2.0 token endpoint +| `auth_oauth2.https.cacertfile` | Path to a file containing PEM-encoded CA certificates. The CA certificates are used to connect to any of these endpoints: `jwks_url`, `token_endpoint`, or the `issuer` +| `auth_oauth2.https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10 +| `auth_oauth2.https.peer_verification` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set.

**Deprecated**: This variable will be soon replaced by `auth_oauth2.https.verify`. Users should stop using this variable +| `auth_oauth2.https.fail_if_no_peer_cert` | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false` +| `auth_oauth2.https.hostname_verification` | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none` +| `auth_oauth2.https.crl_check` | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false +| `auth_oauth2.algorithms` | Restrict [the usable algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support) +| `auth_oauth2.verify_aud` | Whether to verify the [token's `aud`](#token-validation) field or not. The default value is `true` +| `auth_oauth2.resource_servers` | [Multiple OAuth 2.0 resources configuration](#multiple-resource-servers-configuration) +| `auth_oauth2.oauth_providers` | [Multiple OAuth 2.0 providers configuration](#multiple-oauth-providers-configuration) +| `auth_oauth2.default_oauth_provider` | ID of the OAuth 2.0 provider used for the `auth_oauth2.resource_servers`, that did not specify any (via the variable `oauth_provider_id`) or when `auth_oauth2.jwks_url` and `auth_oauth2.issuer` are both missing #### Resource Server ID {#resource-server-id} @@ -256,7 +256,7 @@ Each `auth_oauth2.oauth_providers.{id/index}` entry has the following sub-keys. |------------------------------|----------- | `issuer` | URL of OAuth Provider. RabbitMQ uses this URL to build the OpenId Connect Discovery endpoint by appending the path `.well-known/openid-configuration` to this URL | `token_endpoint` | The URL of the OAuth 2.0 token endpoint. -| `jwks_uri` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must be https.

**Warning**: RabbitMQ uses for each OAuth Provider the variable name `jwks_uri` used by the OpenId Connect Discovery Specification rather than `jwks_url`. +| `jwks_uri` | The URL of the [JWKS endpoint](#jwks-endpoint). According to the [JWT Specification](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2), the endpoint URL must use "https" for schema.

**Warning**: RabbitMQ uses for each OAuth Provider the variable name `jwks_uri` used by the OpenId Connect Discovery Specification rather than `jwks_url`. | `https.cacertfile` | Path to a file containing PEM-encoded CA certificates used to connect `issuer` and/or `jwks_uri` URLs | `https.depth` | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10. | `https.verify` | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set.