Update everything related to scope aliases

Conflicts:
	docs/oauth2-examples-okta.md
	docs/oauth2-examples/index.md
	docs/oauth2.md

Author: MarcialRosales

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
 

docs/oauth2-examples/index.md

@@ -528,116 +528,59 @@ 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/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

docs/oauth2.md

@@ -198,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).
@@ -241,6 +277,7 @@ 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.
 

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

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