diff --git a/docs/oauth2-examples-okta.md b/docs/oauth2-examples-okta.md index 0b5a7c016..0623637fb 100644 --- a/docs/oauth2-examples-okta.md +++ b/docs/oauth2-examples-okta.md @@ -186,11 +186,14 @@ This is totally optional but it can save you time. ## 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 now done. The next step is to configure RabbitMQ +to use the resources created earlier. - - **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**. +The following values will be necessary during the next steps: + +* **okta_client_app_ID**: the Okta app registered above to be used with RabbitMQ +* **okta-Issuer**: the **default Authorization server** +* **okta-Metadata-URI**: the **default Authorization server** Clone [rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next/conf/okta/rabbitmq.conf.tmpl) as `rabbitmq.conf` (in the same folder as `rabbitmq.conf.tmpl`). There is a second configuration file, [advanced.config](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next/conf/okta/advanced.config), @@ -205,6 +208,15 @@ or `{okta-issuer}/.well-known/openid-configuration` 4. Else you need to determine the path that follows the uri in `{okta-issuer}` and update `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`. +The mapping of the roles configured in Okta, such as `monitoring` and `admin`, are configured +at the bottom of the `rabbitmq.conf` file. For example: + +```ini +#... +auth_oauth2.scope_aliases.admin = okta.read:*/* okta.write:*/* okta.configure:*/* okta.tag:administrator +auth_oauth2.scope_aliases.monitoring = okta.tag:management okta.read:*/ +#... +``` ### About OpenId Discovery Endpoint diff --git a/docs/oauth2-examples/index.md b/docs/oauth2-examples/index.md index b4c6ab8ad..423b723ce 100644 --- a/docs/oauth2-examples/index.md +++ b/docs/oauth2-examples/index.md @@ -528,107 +528,48 @@ make curl-with-token URL=http://localhost:15672/api/overview TOKEN=$(bin/jwt_tok ### Using Scope Aliases {#using-scope-aliases} -*Custom scopes*? are any scope whose format is not compliant with RabbitMQ format. -For instance, `api://rabbitmq:Read.All` is one of the custom scopes you will use in this use case. +This example demonstrates how to use custom scopes with RabbitMQ. -#### How to Configure RabbitMQ to Use a Custom Scope Mapping +**UAA** identity provider has been configured with two clients (`producer_with_roles` +and `consumer_with_roles`) with the following custom scopes: -See below a sample RabbitMQ configuration where you map `api://rabbitmq:Read.All` -custom scope to `rabbitmq.read:*/*` RabbitMQ scope. + `producer_with_roles` with + - `api://rabbitmq:producer`. -``` erl -{rabbitmq_auth_backend_oauth2, [ - %%..., - {scope_aliases, #{ - <<"api://rabbitmq:Read.All">> => [<<"rabbitmq.read:*/*">>], - ... - }, - %%... -]} -``` - -Additionally, you can map a custom scope to many RabbitMQ scopes. For instance below you -are mapping the role `api://rabbitmq:producer` to 3 RabbitMQ scopes which grants -`read`, `write` and `configure` access on any resource and on any vhost: - -``` erl -{rabbitmq_auth_backend_oauth2, [ - %% ..., - - {scope_aliases, #{ - <<"api://rabbitmq:producer">> => [ - <<"rabbitmq.read:*/*">>, - <<"rabbitmq.write:*/*">>, - <<"rabbitmq.configure:*/*">> - ] - }}, - %% ... -]} -``` - -#### Scopes Aliases in JWT Tokens + `consumer_with_roles` with + - `api://rabbitmq:Read.All`. + - `api://rabbitmq:Write.All`. + - `api://rabbitmq:Configure.All`. + - `api://rabbitmq:Administrator`. -If you do not configure RabbitMQ OAuth 2.0 plugin with `extra_scopes_source`, RabbitMQ -expects the `scope` token's field to carry *custom scopes*. For instance, below you have a sample JWT -token where the custom scopes are in the `scope` field : +For more information about scope aliases, check out +the [section](./oauth2#scope-aliases) that explains it in more detail. -```javascript -{ - "sub": "producer", - "scope": [ - "api://rabbitmq:producer", - "api://rabbitmq:Administrator" - ], - "aud": [ - "rabbitmq" - ] -} -``` +#### How to Configure Scope Aliases -Now, let's say you do configure RabbitMQ OAuth 2.0 plugin with `extra_scopes_source` as shown below: +This is the configuration required to map those custom scopes to RabbitMQ scopes. +:::tip +Since RabbitMQ 4.1, it is possible to configure **scope aliases** using the [ini-like](./configure#config-file) configuration style. Earlier versions only supported +the legacy Erlang-style. +::: ```ini -# ... -auth_oauth2.resource_server_id = rabbitmq -auth_oauth2.additional_scopes_key = roles -# ... -``` - -With this configuration, RabbitMQ expects *custom scopes* in the field `roles` and -the `scope` field is ignored. +auth_oauth2.scope_aliases.1.alias = api://rabbitmq:Read.All +auth_oauth2.scope_aliases.1.scope = rabbitmq.read:*/* -```javascript -{ - "sub": "rabbitmq-client-code", - "roles": "api://rabbitmq:Administrator.All", - "aud": [ - "rabbitmq" - ] -} -``` +auth_oauth2.scope_aliases.2.alias = api://rabbitmq:Write.All +auth_oauth2.scope_aliases.2.scope = rabbitmq.write:*/* -#### UAA Configuration +auth_oauth2.scope_aliases.3.alias = api://rabbitmq:Configure.All +auth_oauth2.scope_aliases.3.scope = rabbitmq.configure:*/* -To demonstrate this new capability you have configured UAA with two Oauth 2.0 clients. One -called `producer_with_roles` with the *custom scope* `api://rabbitmq:producer` and `consumer_with_roles` with -`api://rabbitmq:Read:All,api://rabbitmq:Configure:All,api://rabbitmq:Write:All`. -> You are granting configure and write permissions to the consumer because you have configured perf-test to declare -resources regardless whether it is a producer or consumer application. +auth_oauth2.scope_aliases.3.alias = api://rabbitmq:Administrator +auth_oauth2.scope_aliases.3.scope = rabbitmq.tag:administrator -These two uaac commands declare the two OAuth 2.0 clients above. You are adding an extra scope called `rabbitmq.*` so -that UAA populates the JWT claim `aud` with the value `rabbitmq`. RabbitMQ expects `aud` to match the value you -configure RabbitMQ with in the `resource_server_id` field. +auth_oauth2.scope_aliases.4.alias = api://rabbitmq:producer +auth_oauth2.scope_aliases.4.scope = rabbitmq.read:*/* rabbitmq.write:*/* rabbitmq.configure:*/* rabbitmq.tag:management -```bash -uaac client add producer_with_roles --name producer_with_roles \ - --authorities "rabbitmq.*,api://rabbitmq:producer,api://rabbitmq:Administrator" \ - --authorized_grant_types client_credentials \ - --secret producer_with_roles_secret -uaac client add consumer_with_roles --name consumer_with_roles \ - --authorities "rabbitmq.* api://rabbitmq:read:All" \ - --authorized_grant_types client_credentials \ - --secret consumer_with_roles_secret ``` @@ -636,8 +577,10 @@ uaac client add consumer_with_roles --name consumer_with_roles \ In the OAuth 2.0 tutorial repository, there are two RabbitMQ configuration files ready to be used, for UAA: -- [conf/uaa/advanced-scope-aliases.config](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/uaa/advanced-scope-aliases.config): configures a set of scope aliases. -- [conf/uaa/rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/uaa/rabbitmq.conf) : configure the rest of oauth2 configuration in addition to configuring `extra_scope` as another claim from where to read scopes from +* [conf/uaa/advanced-scope-aliases.config](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/uaa/advanced-scope-aliases.config): + configures a set of scope aliases. +* [conf/uaa/rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/uaa/rabbitmq.conf): + configure the rest of oauth2 configuration in addition to configuring `extra_scope` as another claim from where to read scopes from #### Demo 1: Launch RabbitMQ with custom scopes in scope field diff --git a/docs/oauth2.md b/docs/oauth2.md index b608140c3..ab9224556 100644 --- a/docs/oauth2.md +++ b/docs/oauth2.md @@ -79,7 +79,7 @@ auth_backends.1 = rabbit_auth_backend_oauth2 Next, let's take a look at the workflows the OAuth 2 plugin supports. -### Prerequisites {#prerequisites} +## Prerequisites {#prerequisites} To use the OAuth 2 plugin, all RabbitMQ nodes must be @@ -116,7 +116,7 @@ auth_oauth2.discovery_endpoint_params.appid = some-app-id More detail is included in the next section about what happens during the authentication and how to configure OAuth 2.0 beyond the basic configuration shown previously. -### Authorization Flow {#authorization-flow} +## Authorization Flow {#authorization-flow} This plugin does not communicate with any OAuth 2.0 provider in order to authenticate user and grants access. Instead, it decodes an access token provided by the client and authorises a user based on the scopes found in the token. @@ -138,7 +138,7 @@ In chronological order, here is the sequence of events that occur when a client 5. RabbitMQ validates that the token has the **audience** claim and whose value matches the `resource_server_id` (this operation can be deactivated by setting `auth_oauth2.verify_aud` to `false`). 6. RabbitMQ translates the **scopes** found in the token into RabbitMQ **permissions** (the same permissions used in the RabbitMQ's internal database). -### Variables configurable in rabbitmq.conf {#variables-configurable} +## Variables Configurable in rabbitmq.conf {#variables-configurable} | Key | Documentation |--------------------------------------------|----------- @@ -150,8 +150,6 @@ In chronological order, here is the sequence of events that occur when a client | `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 that is used to either discover endpoints such as `jwks_uri` and/or where to redirect RabbitMQ management users to login and get a token. -| `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_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. Optional if you set `auth_oauth2.issuer`. If this URL is set, it overrides the `jwks_uri` discovered via the discovery endpoint. | `auth_oauth2.jwks_url` | This variable is **deprecated** and you should use instead `auth_oauth2.jwks_uri`. In RabbitMQ 4.2.0, this variable will be removed. In the meantime, RabbitMQ supports it until you change your configuration. | `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. @@ -168,7 +166,7 @@ In chronological order, here is the sequence of events that occur when a client | `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_uri` and `auth_oauth2.issuer` are both missing. -#### Resource Server ID {#resource-server-id} +## Resource Server ID {#resource-server-id} A RabbitMQ cluster must have at least one resource server identifier configured. If it has just one resource, this is configured in the `auth_oauth2.resource_server_id` variable and it is **mandatory**. If the RabbitMQ cluster has more than one OAuth resource then they are configured under `auth_oauth2.resource_servers.` and in this case `auth_oauth2.resource_server_id` variable is not mandatory. @@ -177,7 +175,7 @@ RabbitMQ uess the resource server identity for these two purposes: - To validate the token's audience (`aud`) whose value must contain the resource server identifier. This validation can be disabled though. - To initiate the OAuth 2.0 Authorization Code flow in the Management UI. This is the flow used to authenticate a user and to get its access token. RabbitMQ must include the resource server identifier in the request's attribute called `resource`. -#### Scope prefix {#scope-prefix} +## Scope Prefix {#scope-prefix} OAuth 2.0 tokens use scopes to communicate what set of permissions particular client are granted. The scopes are free form strings. @@ -198,7 +196,56 @@ auth_oauth2.scope_prefix = '' ... ``` -#### Signing keys files {#signing-key-files} +## Scope Aliases {#scope-aliases} + +:::important + +Scope aliases are necessary when scopes in the RabbitMQ format cannot be +configured on the identity provider (IDP) side + +::: + +A scope alias is a mapping between a custom JWT token scope and a set of RabbitMQ-specific scopes. A custom +scope can also be defined as any scope which is not recogonized by RabbitMQ's OAuth 2 subsystem. + +Scope aliases are necessary when scopes in the RabbitMQ format cannot be +configured on the identity provider (IDP) side. Instead, a set of names is configured +on the IDP side, and mapped to a set of scoped that RabbitMQ can parse and use. + +For instance, let's consider an identity provider with the following two roles: + +* `admin` +* `developer` + +These roles should be mapped to the following RabbitMQ scopes: + +* `admin` to `rabbitmq.tag:administrator rabbitmq.read:*/` +* `developer` to `rabbitmq.tag:management rabbitmq.read:*/* rabbitmq.write:*/* rabbitmq.configure:*/*` + +The following `rabbitmq.conf` example performs the aforementioned mapping using scope aliases. The mapping can be one-to-one or one-to-many: + +```ìni +# ... +# the "admin" role above +auth_oauth2.scope_aliases.admin = rabbitmq.tag:administrator rabbitmq.read:*/ +# the "developer" role above +auth_oauth2.scope_aliases.developer = rabbitmq.tag:management rabbitmq.read:*/* rabbitmq.write:*/* rabbitmq.configure:*/* +# ... +``` + +Sometimes an alias may have to use special characters and symbols including the separator character, `.`. +In those cases, configure the scope aliases as follows: + +```ìni +# ... +auth_oauth2.scope_aliases.1.alias = api://admin +auth_oauth2.scope_aliases.1.scope = rabbitmq.tag:administrator rabbitmq.read:*/ +auth_oauth2.scope_aliases.2.alias = api://developer.All +auth_oauth2.scope_aliases.2.scope = rabbitmq.tag:management rabbitmq.read:*/* rabbitmq.write:*/* rabbitmq.configure:*/* +# ... +``` + +## Signing Keys Files {#signing-key-files} The following configuration declares two signing keys and configures the kid of the default signing key. For more information check the section [Configure Signing keys](#configure-signing-keys). @@ -214,7 +261,7 @@ auth_oauth2.algorithms.1 = HS256 auth_oauth2.algorithms.2 = RS256 ``` -#### JWKS endpoint {#jwks-endpoint} +## JWKS endpoint {#jwks-endpoint} The following configuration sets the JWKS endpoint from which RabbitMQ downloads the signing keys using the configured CA certificate and TLS variables. @@ -231,7 +278,7 @@ auth_oauth2.algorithms.2 = RS256 ``` -#### Multiple Resource Servers configuration {#multiple-resource-servers-configuration} +## Multiple Resource Servers Сonfiguration {#multiple-resource-servers-configuration} Each `auth_oauth2.resource_servers..` entry has the following variables shown in the table below. Except for the variables `id` and `oauth_provider_id`, if a resource does not configure a variable, RabbitMQ uses the variable configured at the root level. For instance, if the resource `auth_oauth2.resource_servers.prod` does not configure `preferred_username_claims` variable, RabbitMQ uses the value configured in `auth_oauth2.preferred_username_claims` for the resource `prod`. @@ -241,6 +288,7 @@ Each `auth_oauth2.resource_servers..` entry has the following variable | `resource_server_type` | The Resource Server Type required when using [Rich Authorization Request](#rich-authorization-request) token format. | `additional_scopes_key` | Configure the plugin to look for scopes in other fields (maps to `additional_rabbitmq_scopes` in the old format). | `scope_prefix` | [Configure the prefix for all scopes](#scope-prefix). The default value is `auth_oauth2.resource_server_id` followed by the dot `.` character. +| `scope_aliases` | [Configure scope aliases](#scope-aliases) | `preferred_username_claims` | [List of the JWT claims](#preferred-username-claims) to look for the username associated with the token separated by commas. | `oauth_provider_id` | The identifier of the OAuth Provider associated to this resource. RabbitMQ uses the signing keys issued by this OAuth Provider to validate tokens whose audience matches this resource's id. @@ -259,7 +307,7 @@ auth_oauth2.resource_servers.2.id = dev See the advanced usage section called [Multiple Resource Servers](#multiple-resource-servers) for more information on how to configure them. -#### Multiple OAuth Providers configuration {#multiple-oauth-providers-configuration} +## Multiple OAuth Providers Сonfiguration {#multiple-oauth-providers-configuration} Each `auth_oauth2.oauth_providers.{id/index}` entry has the following sub-keys. diff --git a/versioned_docs/version-3.13/oauth2-examples-okta.md b/versioned_docs/version-3.13/oauth2-examples-okta.md index f319f2ab5..42412f1c2 100644 --- a/versioned_docs/version-3.13/oauth2-examples-okta.md +++ b/versioned_docs/version-3.13/oauth2-examples-okta.md @@ -150,14 +150,15 @@ Once you've added the user to the appropriate groups and apps, they should have ## 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. +The configuration on the Okta side is now done. The next step is to configure RabbitMQ +to use the resources created earlier. [rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/rabbitmq.conf) is a RabbitMQ configuration to **enable okta as OAuth 2.0 authentication backend** for the RabbitMQ OAuth2 and Management plugins. And [advanced.config](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/advanced.config) is the RabbitMQ advanced configuration that maps RabbitMQ scopes to the permissions previously configured in Okta. -Update it with the following values (you should have noted these in the previous steps): +Update it with the following values from the earlier steps: - - **okta-domain-name** associated to your okta domain name. - - **okta_client_app_ID** associated to the okta app that you registered in okta for rabbitMQ. +* **okta-domain-name**: the Okta domain name +* **okta_client_app_ID**: the Okta app registered above to be used with RabbitMQ ## Start RabbitMQ diff --git a/versioned_docs/version-3.13/oauth2.md b/versioned_docs/version-3.13/oauth2.md index 050fa9a20..1f235bd0d 100644 --- a/versioned_docs/version-3.13/oauth2.md +++ b/versioned_docs/version-3.13/oauth2.md @@ -78,7 +78,7 @@ auth_backends.1 = rabbit_auth_backend_oauth2 Next, let's take a look at the workflows the OAuth 2 plugin supports. -### Prerequisites {#prerequisites} +## Prerequisites {#prerequisites} To use the OAuth 2 plugin, all RabbitMQ nodes must be @@ -109,7 +109,7 @@ Also, the `https://my-oauth2-provider.com/realm/rabbitmq/.well-known/openid-conf More detail is included in the next section about what happens during the authentication and how to configure OAuth 2.0 beyond the basic configuration shown previously. -### Authorization Flow {#authorization-flow} +## Authorization Flow {#authorization-flow} This plugin does not communicate with any OAuth 2.0 provider in order to authenticate user and grants access. Instead, it decodes an access token provided by the client and authorises a user based on the scopes found in the token. @@ -131,7 +131,7 @@ In chronological order, here is the sequence of events that occur when a client 5. RabbitMQ validates that the token has the **audience** claim and whose value matches the `resource_server_id` (this operation can be deactivated by setting `auth_oauth2.verify_aud` to `false`). 6. RabbitMQ translates the **scopes** found in the token into RabbitMQ **permissions** (the same permissions used in the RabbitMQ's internal database). -### Variables configurable in rabbitmq.conf {#variables-configurable} +## Variables Сonfigurable in rabbitmq.conf {#variables-configurable} | Key | Documentation |--------------------------------------------|----------- @@ -158,7 +158,7 @@ In chronological order, here is the sequence of events that occur when a client | `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} +## Resource Server ID {#resource-server-id} A RabbitMQ cluster must have at least one resource server identifier configured. If it has just one resource, this is configured in the `auth_oauth2.resource_server_id` variable and it is **mandatory**. If the RabbitMQ cluster has more than one OAuth resource then they are configured under `auth_oauth2.resource_servers.` and in this case `auth_oauth2.resource_server_id` variable is not mandatory. @@ -167,7 +167,7 @@ RabbitMQ uess the resource server identity for these two purposes: - To validate the token's audience (`aud`) whose value must contain the resource server identifier. This validation can be disabled though. - To initiate the OAuth 2.0 Authorization Code flow in the Management UI. This is the flow used to authenticate a user and to get its access token. RabbitMQ must include the resource server identifier in the request's attribute called `resource`. -#### Scope prefix {#scope-prefix} +## Scope Prefix {#scope-prefix} OAuth 2.0 tokens use scopes to communicate what set of permissions particular client are granted. The scopes are free form strings. @@ -181,7 +181,7 @@ auth_oauth2.scope_prefix = api:// ... ``` -#### Signing keys files {#signing-key-files} +## Signing keys files {#signing-key-files} The following configuration declares two signing keys and configures the kid of the default signing key. For more information check the section [Configure Signing keys](#configure-signing-keys). @@ -197,7 +197,7 @@ auth_oauth2.algorithms.1 = HS256 auth_oauth2.algorithms.2 = RS256 ``` -#### JWKS endpoint {#jwks-endpoint} +## JWKS endpoint {#jwks-endpoint} The followibng configuration sets the JWKS endpoint from which RabbitMQ downloads the signing keys using the configured CA certificate and TLS variables. @@ -213,7 +213,7 @@ auth_oauth2.algorithms.1 = HS256 auth_oauth2.algorithms.2 = RS256 ``` -#### Multiple Resource Servers configuration {#multiple-resource-servers-configuration} +## Multiple Resource Servers configuration {#multiple-resource-servers-configuration} Each `auth_oauth2.resource_servers..` entry has the following variables shown in the table below. Except for the variables `id` and `oauth_provider_id`, if a resource does not configure a variable, RabbitMQ uses the variable configured at the root level. For instance, if the resource `auth_oauth2.resource_servers.prod` does not configure `preferred_username_claims` variable, RabbitMQ uses the value configured in `auth_oauth2.preferred_username_claims` for the resource `prod`. @@ -239,7 +239,7 @@ auth_oauth2.resource_servers.2.id = dev See the advanced usage section called [Multiple Resource Servers](#multiple-resource-servers) for more information on how to configure them. -#### Multiple OAuth Providers configuration {#multiple-oauth-providers-configuration} +## Multiple OAuth Providers Configuration {#multiple-oauth-providers-configuration} Each `auth_oauth2.oauth_providers..` entry has the following variables. diff --git a/versioned_docs/version-4.0/oauth2-examples-okta.md b/versioned_docs/version-4.0/oauth2-examples-okta.md index f319f2ab5..42412f1c2 100644 --- a/versioned_docs/version-4.0/oauth2-examples-okta.md +++ b/versioned_docs/version-4.0/oauth2-examples-okta.md @@ -150,14 +150,15 @@ Once you've added the user to the appropriate groups and apps, they should have ## 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. +The configuration on the Okta side is now done. The next step is to configure RabbitMQ +to use the resources created earlier. [rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/rabbitmq.conf) is a RabbitMQ configuration to **enable okta as OAuth 2.0 authentication backend** for the RabbitMQ OAuth2 and Management plugins. And [advanced.config](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/main/conf/okta/advanced.config) is the RabbitMQ advanced configuration that maps RabbitMQ scopes to the permissions previously configured in Okta. -Update it with the following values (you should have noted these in the previous steps): +Update it with the following values from the earlier steps: - - **okta-domain-name** associated to your okta domain name. - - **okta_client_app_ID** associated to the okta app that you registered in okta for rabbitMQ. +* **okta-domain-name**: the Okta domain name +* **okta_client_app_ID**: the Okta app registered above to be used with RabbitMQ ## Start RabbitMQ diff --git a/versioned_docs/version-4.0/oauth2.md b/versioned_docs/version-4.0/oauth2.md index f54a907b4..ce3c33b0a 100644 --- a/versioned_docs/version-4.0/oauth2.md +++ b/versioned_docs/version-4.0/oauth2.md @@ -78,7 +78,7 @@ auth_backends.1 = rabbit_auth_backend_oauth2 Next, let's take a look at the workflows the OAuth 2 plugin supports. -### Prerequisites {#prerequisites} +## Prerequisites {#prerequisites} To use the OAuth 2 plugin, all RabbitMQ nodes must be @@ -109,7 +109,7 @@ Also, the `https://my-oauth2-provider.com/realm/rabbitmq/.well-known/openid-conf More detail is included in the next section about what happens during the authentication and how to configure OAuth 2.0 beyond the basic configuration shown previously. -### Authorization Flow {#authorization-flow} +## Authorization Flow {#authorization-flow} This plugin does not communicate with any OAuth 2.0 provider in order to authenticate user and grants access. Instead, it decodes an access token provided by the client and authorises a user based on the scopes found in the token. @@ -131,7 +131,7 @@ In chronological order, here is the sequence of events that occur when a client 5. RabbitMQ validates that the token has the **audience** claim and whose value matches the `resource_server_id` (this operation can be deactivated by setting `auth_oauth2.verify_aud` to `false`). 6. RabbitMQ translates the **scopes** found in the token into RabbitMQ **permissions** (the same permissions used in the RabbitMQ's internal database). -### Variables configurable in rabbitmq.conf {#variables-configurable} +## Variables Сonfigurable in rabbitmq.conf {#variables-configurable} | Key | Documentation |--------------------------------------------|----------- @@ -159,7 +159,7 @@ In chronological order, here is the sequence of events that occur when a client -#### Resource Server ID {#resource-server-id} +## Resource Server ID {#resource-server-id} A RabbitMQ cluster must have at least one resource server identifier configured. If it has just one resource, this is configured in the `auth_oauth2.resource_server_id` variable and it is **mandatory**. If the RabbitMQ cluster has more than one OAuth resource then they are configured under `auth_oauth2.resource_servers.` and in this case `auth_oauth2.resource_server_id` variable is not mandatory. @@ -168,7 +168,7 @@ RabbitMQ uess the resource server identity for these two purposes: - To validate the token's audience (`aud`) whose value must contain the resource server identifier. This validation can be disabled though. - To initiate the OAuth 2.0 Authorization Code flow in the Management UI. This is the flow used to authenticate a user and to get its access token. RabbitMQ must include the resource server identifier in the request's attribute called `resource`. -#### Scope prefix {#scope-prefix} +## Scope Prefix {#scope-prefix} OAuth 2.0 tokens use scopes to communicate what set of permissions particular client are granted. The scopes are free form strings. @@ -189,7 +189,7 @@ auth_oauth2.scope_prefix = '' ... ``` -#### Signing keys files {#signing-key-files} +## Signing keys files {#signing-key-files} The following configuration declares two signing keys and configures the kid of the default signing key. For more information check the section [Configure Signing keys](#configure-signing-keys). @@ -205,7 +205,7 @@ auth_oauth2.algorithms.1 = HS256 auth_oauth2.algorithms.2 = RS256 ``` -#### JWKS endpoint {#jwks-endpoint} +## JWKS endpoint {#jwks-endpoint} The followibng configuration sets the JWKS endpoint from which RabbitMQ downloads the signing keys using the configured CA certificate and TLS variables. @@ -221,7 +221,7 @@ auth_oauth2.algorithms.1 = HS256 auth_oauth2.algorithms.2 = RS256 ``` -#### Multiple Resource Servers configuration {#multiple-resource-servers-configuration} +## Multiple Resource Servers configuration {#multiple-resource-servers-configuration} Each `auth_oauth2.resource_servers..` entry has the following variables shown in the table below. Except for the variables `id` and `oauth_provider_id`, if a resource does not configure a variable, RabbitMQ uses the variable configured at the root level. For instance, if the resource `auth_oauth2.resource_servers.prod` does not configure `preferred_username_claims` variable, RabbitMQ uses the value configured in `auth_oauth2.preferred_username_claims` for the resource `prod`.