Update everything related to scope aliases

MarcialRosales · MarcialRosales · commit e369988313c4 · 2024-10-09T15:39:05.000+02:00
diff --git a/docs/oauth2-examples-okta.md b/docs/oauth2-examples-okta.md
@@ -195,12 +195,9 @@ For that, you will need the following values from the previous steps:
 * **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
+Copy [rabbitmq.conf.tmpl](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next/conf/okta/rabbitmq.conf.tmpl) from the tutorial repository
 to `rabbitmq.conf`. It must be in the same directory as `rabbitmq.conf.tmpl`.
 
-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.
-
 Edit `rabbitmq.conf` and proceed as follows:
 
 1. Replace `{okta_client_app_ID}` with your **okta_client_app_ID**
@@ -210,6 +207,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, i.e. `monitoring` and `admin`, are configured
+at the bottom of the `rabbitmq.conf` file. Here it is configuration for convenience:
+
+```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 the OpenId Discovery Endpoint
 
diff --git a/docs/oauth2-examples/index.md b/docs/oauth2-examples/index.md
@@ -530,116 +530,57 @@ 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
 ```
 
 
 #### RabbitMQ Configuration
 
 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/main/conf/uaa/advanced-scope-aliases.config): configures a set of scope aliases.
-- [conf/uaa/rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/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/scope-aliases.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/uaa/scope-aliases.conf): 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
@@ -146,18 +146,17 @@ 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. 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 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.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.scope_aliases`                | [Configure scope aliases](#scope-aliases). See this [example](./oauth2-examples#using-scope-aliases).
+| `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 that is used to discover endpoints such as `jwk_uri` and others (https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
+| `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. <p/> **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`
@@ -199,6 +198,42 @@ auth_oauth2.scope_prefix = ''
 ...
 ```
 
+#### Scope aliases {#scope-aliases}
+
+An scope alias is a mapping between a custom scope and a RabbitMQ's scope. A custom
+scope is any scope which is not recogonized by RabbitMQ.
+
+Scope aliases are necessary when you cannot create RabbitMQ scopes in your
+identity provider. Instead you have to name them following a format which is not
+recognizable by RabbitMQ.
+
+For instance, say you have these two roles in your identity provider:
+  - `admin`.
+  - `developer`.
+
+Also say that you want to map those roles to the following RabbitMQ scopes:
+  - `admin` to `rabbitmq.tag:administrator rabbitmq.read:*/`
+  - `developer` to `rabbitmq.tag:management rabbitmq.read:*/* rabbitmq.write:*/* rabbitmq.configure:*/*`
+
+You configure the scope aliases as follows. The mapping can be 1:1 or 1:many:
+```ìni
+# ...
+auth_oauth2.scope_aliases.admin = rabbitmq.tag:administrator rabbitmq.read:*/
+auth_oauth2.scope_aliases.developer = rabbitmq.tag:management rabbitmq.read:*/* rabbitmq.write:*/* rabbitmq.configure:*/*
+# ...
+```
+
+Sometimes, the alias is not made of a single word but instead it uses special characters
+and symbols including the separator character `.`. In those cases, you can 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).
@@ -242,12 +277,13 @@ Each `auth_oauth2.resource_servers.<id/index>.` 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.
 
 All available configurable parameters for each OAuth 2 provider is documented [in a separate section](#multiple-oauth-providers-configuration).
 
-Usually, a numeric value is used as `index`, for example `auth_oauth2.resource_servers.1.id = rabbit_prod`. However, it can be any string, for example `auth_oauth2.resource_servers.rabbit_prod.jwks_url = http://some_url`. By default, the `index` is the resource server's id. However, you can override it via the `id` variable like in `auth_oauth2.resource_servers.1.id = rabbit_prod`.
+Usually, a numeric value is used as `index`, for example `auth_oauth2.resource_servers.1.id = rabbit_prod`. However, it can be any string, for example `auth_oauth2.resource_servers.rabbit_prod.issuer = http://some_url`. By default, the `index` is the resource server's id. However, you can override it via the `id` variable like in `auth_oauth2.resource_servers.1.id = rabbit_prod`.
 
 Here is an example which configures two resources (`prod` and `dev`) which are used by the users and clients managed by
 the same identity provider whose issuer url is `https://my-idp.com/`:
