Explain additional_scopes_key configuration

Author: MarcialRosales

docs/oauth2-examples-keycloak.md

@@ -69,6 +69,14 @@ make start-rabbitmq
 RabbitMQ is deployed with TLS enabled and Keycloak is configured with the corresponding `redirect_url` which uses https.
 :::
 
+:::important 
+RabbitMQ is configured to read the scopes from the custom claim [extra_scope](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/keycloak/rabbitmq.conf#L11) and 
+by default from the standard claim `scope`. 
+However, if your scopes are deep in a map/list structure like `authorization.permissions.scopes`
+or under `realm_access.roles` or `resource_access.account.roles`, you can configure
+RabbitMQ to use those locations instead. See the section [Use a different token field for the scope](./oauth2#use-different-token-field) for more information.
+:::
+
 ## Access Management api
 
 To access the management api run the following command. It uses the client [mgt_api_client](https://keycloak:8443/admin/master/console/#/test/clients/c5be3c24-0c88-4672-a77a-79002fcc9a9d/settings) which has the scope [rabbitmq.tag:administrator](https://keycloak:8443/admin/master/console/#/test/client-scopes/f6e6dd62-22bf-4421-910e-e6070908764c/settings).

docs/oauth2.md

@@ -144,7 +144,7 @@ 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.additional_scopes_key`        | [Configure](#use-different-token-field) the plugin to look for scopes in other fields. |
 | `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.
@@ -252,9 +252,6 @@ The following configuration declares two signing keys and configures the kid of
 
 ```ini
 auth_oauth2.resource_server_id = new_resource_server_id
-auth_oauth2.additional_scopes_key = my_custom_scope_key
-auth_oauth2.preferred_username_claims.1 = username
-auth_oauth2.preferred_username_claims.2 = user_name
 auth_oauth2.default_key = id1
 auth_oauth2.signing_keys.id1 = test/config_schema_SUITE_data/certs/key.pem
 auth_oauth2.signing_keys.id2 = test/config_schema_SUITE_data/certs/cert.pem
@@ -571,26 +568,116 @@ If a symmetric key is used, the configuration looks like this:
 
 ### Use a different token field for the scope {#use-different-token-field}
 
-By default the plugin looks for the `scope` key in the token, you can configure the plugin to also look in other fields using the `extra_scopes_source` variable. Values format accepted are scope as **string** or **list**
+The plugin always extracts the scopes from the `scope` claim. However,
+you can also configure the plugin to look in other claims using the `auth_oauth2.additional_scopes_key` variable. 
 
-```ini
-auth_oauth2.resource_server_id = my_rabbit_server
-auth_oauth2.additional_scopes_key = my_custom_scope_key
-```
+The scopes found in the `scope` claim must be of these two value types:
+- **string separated by spaces** like `my_id.configure:*/* my_id.read:*/* my_id.write:*/*`
+- **list** like `["my_id.configure:*/*", "my_id.read:*/*", "my_id.write:*/*"]`
+
+The scopes found in any claim listed in the `auth_oauth2.additional_scopes_key` variable can be 
+of several types in addition to the two value types supported by the `scope` claim mentioned earlier.
+
+#### Map of scopes indexed by resource_server_id {#map-of-scopes-indexed-by-resource-id}
+
+This is an example of a token where scopes are not yet prefixed with the `resource_server_id`
+but are indexed by the `resource_server_id`:
 
-Token sample:
 ```ini
 {
  "exp": 1618592626,
  "iat": 1618578226,
  "aud" : ["my_id"],
  ...
- "scope_as_string": "my_id.configure:*/* my_id.read:*/* my_id.write:*/*",
- "scope_as_list": ["my_id.configure:*/*", "my_id.read:*/*", "my_id.write:*/*"],
- ...
+ "complex_claim_as_string": {
+    "rabbitmq": ["configure:*/* read:*/* write:*/*"]
+ },
+ "complex_claim_as_list": {
+    "rabbitmq": ["configure:vhost1/*", "read:vhost1/*", "write:vhost1/*"] 
  }
+ ...
+}
+```
+
+With the following plugin configuration, the plugin reads the scopes from two
+additional claims: `complex_claim_as_string` and `complex_claim_as_list`. 
+The plugin reads the scopes and adds the key value as prefix, for instance, 
+given the scope `configure:*/*` it produces `rabbitmq.configure:*/*`.
+
+```ini
+auth_oauth2.resource_server_id = my_rabbit_server
+auth_oauth2.additional_scopes_key = complex_claim_as_string complex_claim_as_list
+```
+
+#### Scopes nested deep in Maps and Lists
+
+This is the case for tokens issued by **Keycloak** Identity Provider but can be
+applied to any token from any provider.
+
+This first token format stores scopes deep in maps and lists.
+```json
+{
+  "authorization": {
+    "permissions": [
+      {
+        "scopes": [
+          "rabbitmq-resource.read:*/*"
+        ],
+        "rsid": "2c390fe4-02ad-41c7-98a2-cebb8c60ccf1",
+        "rsname": "allvhost"
+      },
+      {
+        "scopes": [
+          "rabbitmq-resource.write:vhost1/*"
+        ],
+        "rsid": "e7f12e94-4c34-43d8-b2b1-c516af644cee",
+        "rsname": "vhost1"
+      },
+      {
+        "scopes": [
+          "rabbitmq-resource.tag:administrator"
+        ],
+        "rsid": "12ac3d1c-28c2-4521-8e33-0952eff10bd9"        
+      }
+    ]
+  },
+  "scope": "email profile rabbitmq-resource.tag:monitoring",
+}
 ```
 
+Given the following configuration:
+```ini
+auth_oauth2.resource_server_id = my_rabbit_server
+auth_oauth2.additional_scopes_key = authorization.permissions.scopes 
+```
+
+The plugin navigates the token structure following this logic:
+1. It looks up the claim `authorization`.
+2. It finds a map, it then looks for the next claim `permissions`.
+3. This time, it finds a list of maps. It goes over all the items in the list.
+4. For each map in the list, it looks up the next claim `scopes`.
+5. The value can be a list of scopes or a comma-separated string of scopes or 
+a [map of scopes indexed by resource_server_id](#map-of-scopes-indexed-by-resource-id).
+
+Additionally, the plugin always reads the scopes from the official `scope` claim.
+
+With the above token and plugin's configuration, the list of scopes are following:
+- `rabbitmq-resource.tag:monitoring`
+- `rabbitmq-resource.read:*/*`
+- `rabbitmq-resource.write:vhost1/*`
+- `rabbitmq-resource.tag:administrator`
+
+In summary, the plugin is able to navigate the token to find the scopes 
+using the appropriate path. Each intermediary stage, for instance, after 
+finding `authorization` and/or `permissions` keys, the value can be another Map or 
+a List of Maps. The last stage, after finding the last `scopes` key, the value 
+can be any of any of the value types explained in the previous section. 
+
+These are:
+- **string separated by spaces** like `my_id.configure:*/* my_id.read:*/* my_id.write:*/*`
+- **list** like `["my_id.configure:*/*", "my_id.read:*/*", "my_id.write:*/*"]`
+- [Map of scopes indexed by resource server id](#map-of-scopes-indexed-by-resource-id)
+
 ### Preferred username claims {#preferred-username-claims}
 
 The username associated with the token must be available to RabbitMQ so that this username is displayed in the RabbitMQ Management UI.