Explain keycloak jwt token formats

Author: MarcialRosales

docs/oauth2-examples-keycloak.md

@@ -28,6 +28,66 @@ and Keycloak as Authorization Server using the following flows:
 * Access management HTTP API
 * Application authentication and authorization
 
+## Keycloak JWT payloads
+
+Keycloak may issue two types of JWT payloads. 
+
+One type of payload is found in a [Requesting Party Token](./oauth2#requesting-party-token). 
+RabbitMQ supports this type of token and it extracts the scopes from it. 
+You do not need to configure anything.
+
+A second type of payload is the following. The claim `roles` is not strictily 
+speaking part of Keycloak official claims. Instead, it is a custom claim configured
+by the user via the Keycloak administration console.
+
+```json 
+{
+  "realm_access": {
+    "roles": [
+      "offline_access",
+      "uma_authorization",
+      "rabbitmq.tag:management",
+    ]
+  },
+  "resource_access": {
+    "account": {
+      "roles": [
+        "manage-account",
+        "manage-account-links",
+        "view-profile",
+        "rabbitmq.write:*/*"
+      ]
+    }
+  },
+  "roles": "rabbitmq.read:*/*",
+  "scope": "profile email"
+}
+```
+
+RabbitMQ does not read the scopes from this token unless you configure it to do so.
+For instance, to configure RabbitMQ to extract the scopes from "roles" under "realm_access",
+you add the following configuration variable:
+
+```json
+auth_oauth2.additional_scopes_key = realm_access.roles
+```
+
+To configure RabbitMQ to also read from "resource_access", you modify the previous 
+configuration as follows:
+
+```json
+auth_oauth2.additional_scopes_key = realm_access.roles resource_access.account.roles 
+```
+
+And finally, if you also want to use the scopes in the claim `roles`, you modify
+the previous configuration:
+
+```json
+auth_oauth2.additional_scopes_key = roles realm_access.roles resource_access.account.roles 
+```
+
+RabbitMQ reads the scopes from all those sources. 
+
 ## Prerequisites to follow this guide
 
 * Docker

docs/oauth2.md

@@ -47,6 +47,7 @@ There's also a companion [troubleshooting guide for OAuth 2-specific problems](.
 * [Preferred username claims](#preferred-username-claims)
 * [Discovery Endpoint params](#discovery-endpoint-params)
 * [Rich Authorization Request](#rich-authorization-request)
+* [Requesting Party Token](#requesting-party-token)
 
 ### [Advanced usage](#advanced-usage)
 
@@ -719,6 +720,54 @@ This is the URL built to access the OpenId Discovery endpoint:
 https://myissuer.com/v2/.well-known/authorization-server?param1=value1&param2=value2
 ```
 
+### Requesting Party Token {#requesting-party-token}
+
+A **Requesting Party Token (RPT)** is a special OAuth 2.0 **access token** 
+issued by an **Authorization Server** in the [User-Managed Access (UMA) 2.0](https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html) framework. 
+It is used by a **Requesting Party** (such as an application or user) to access 
+a protected resource on a Resource Server like RabbitMQ, after being authorized
+based on a resource owner policies.
+
+[Keycloak](./oauth2-examples-keycloak) is one of the Authorization Servers that issues this type of tokens. 
+An RPT is typically a JWT with permissions claims under a claim called `authorization`.
+See the example below. The rest of the claims have been removed from the token for 
+brevity:
+
+```json
+{
+  "authorization": {
+    "permissions": [
+      {
+        "scopes": [
+          "rabbitmq-resource.read:*/*"
+        ],
+        "rsid": "2c390fe4-02ad-41c7-98a2-cebb8c60ccf1",
+        "rsname": "allvhost"
+      },
+      {
+        "scopes": [
+          "rabbitmq-resource:vhost1/*"
+        ],
+        "rsid": "e7f12e94-4c34-43d8-b2b1-c516af644cee",
+        "rsname": "vhost1"
+      },
+      {
+        "rsid": "12ac3d1c-28c2-4521-8e33-0952eff10bd9",        
+        "scopes": [
+          "rabbitmq-resource.tag:administrator"
+        ]
+      }
+    ]
+  },
+  "scope": "email profile",
+}
+```
+
+RabbitMQ supports this token format. It reads all the scopes in all the `permissions`
+claims. If the token also contains the standard `scope` claim, RabbitMQ adds it to the
+list of scopes presented by the token.
+
+
 ### Rich Authorization Request {#rich-authorization-request}
 
 The [Rich Authorization Request](https://oauth.net/2/rich-authorization-requests/) extension provides a way for