Add scope aliases

to the docs and examples

Author: MarcialRosales

docs/oauth2-examples-okta.md

@@ -152,7 +152,7 @@ Once you've added the user to the appropriate groups and apps, they should have
 
 The configuration on Okta side is done. You now have to configure RabbitMQ to use the resources you just created.
 
-[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.
+[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. 
 
 Update it with the following values (you should have noted these in the previous steps):
 

docs/oauth2-examples/index.md

@@ -530,114 +530,51 @@ make curl-with-token URL=http://localhost:15672/api/overview TOKEN=$(bin/jwt_tok
 
 ### Using Scope Aliases {#using-scope-aliases}
 
-In this use case you are going to demonstrate how to configure RabbitMQ to handle
-*custom scopes*. But what are *custom scopes*? They 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.
-
-#### How to Configure RabbitMQ to Use a Custom Scope Mapping
-
-Starting with [RabbitMQ `3.10.0`](https://github.com/rabbitmq/rabbitmq-server/releases/tag/v3.10.0),
-the OAuth 2.0 plugin supports mapping of a scope aliases (arbitrary scope values or "names") to one or more scopes
-in the format that follows the RabbitMQ OAuth 2.0 plugin conventions.
-
-See below a sample RabbitMQ configuration where you map `api://rabbitmq:Read.All`
-custom scope to `rabbitmq.read:*/*` RabbitMQ scope.
-
-``` 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
-
-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 :
+This example demonstrates how to use custom scopes with RabbitMQ. 
+**UAA** identity provider has been configured with two clients (`producer_with_roles`
+and `consumer_with_roles`) with the following custom scopes:
+  `producer_with_roles` with 
+    - `api://rabbitmq:producer`.
+
+  `consumer_with_roles` with  
+    - `api://rabbitmq:Read.All`.
+    - `api://rabbitmq:Write.All`.
+    - `api://rabbitmq:Configure.All`.
+    - `api://rabbitmq:Administrator`.
+    
+For more information about scope aliases, check out
+the [section](./oauth2#scope-aliases) that explains it in more detail. 
+
+#### How to Configure Scope Aliases
+
+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.
+:::
 
-```javascript
-{
-  "sub": "producer",
-  "scope": [
-    "api://rabbitmq:producer",
-    "api://rabbitmq:Administrator"
-  ],
-  "aud": [
-    "rabbitmq"
-  ]
-}
-```
+```ini
+auth_oauth2.scope_aliases.1.alias = api://rabbitmq:Read.All
+auth_oauth2.scope_aliases.1.scope = rabbitmq.read:*/*
 
-Now, let's say you do configure RabbitMQ OAuth 2.0 plugin with `extra_scopes_source` as shown below:
+auth_oauth2.scope_aliases.2.alias = api://rabbitmq:Write.All
+auth_oauth2.scope_aliases.2.scope = rabbitmq.write:*/*
 
+auth_oauth2.scope_aliases.3.alias = api://rabbitmq:Configure.All
+auth_oauth2.scope_aliases.3.scope = rabbitmq.configure:*/*
 
-```ini
-# ...
-auth_oauth2.resource_server_id = rabbitmq
-auth_oauth2.additional_scopes_key = roles
-# ...
-```
+auth_oauth2.scope_aliases.3.alias = api://rabbitmq:Administrator
+auth_oauth2.scope_aliases.3.scope = rabbitmq.tag:administrator
 
-With this configuration, RabbitMQ expects *custom scopes* in the field `roles` and
-the `scope` field is ignored.
+auth_oauth2.scope_aliases.4.alias = api://rabbitmq:producer
+auth_oauth2.scope_aliases.4.scope = rabbitmq.read:*/* rabbitmq.write:*/* rabbitmq.configure:*/* rabbitmq.tag:management
 
-```javascript
-{
-  "sub": "rabbitmq-client-code",
-  "roles": "api://rabbitmq:Administrator.All",
-  "aud": [
-    "rabbitmq"
-  ]
-}
 ```
 
-#### UAA Configuration
-
-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.
 
-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.
+#### Test scope aliases
 
-```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

docs/oauth2.md

@@ -138,7 +138,8 @@ 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.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). 
 | `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).
@@ -188,6 +189,43 @@ 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 can create RabbitMQ scopes in your 
+identity provider. Instead you have to name scopes following a format which is not
+recognizable by RabbitMQ. 
+
+For instance, say you have these two roles in your identity provider:
+  - `admin`. 
+  - `developer`.
+An OAuth token may carry those roles in the claim `scope` or in the claim `roles`. 
+Either way 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_prefix = rabbitmq.
+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 such as `api://admin` or `api://developer`. In those cases, you can configure the scope aliases as follows:
+# ...
+auth_oauth2.scope_prefix = rabbitmq.
+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 
+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).
@@ -230,12 +268,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/`: