[KEYCLOAK-7552] - More documentation about how to push claims

authorization_services/topics.adoc

@@ -78,6 +78,8 @@ include::topics/service-authorization-obtaining-permission.adoc[leveloffset=+2]
 
 include::topics/service-authorization-obtaining-permission-authentication.adoc[leveloffset=+3]
 
+include::topics/service-authorization-pushing-claims.adoc[leveloffset=+3]
+
 include::topics/service-authorization-obtaining-permission-uma.adoc[leveloffset=+2]
 
 include::topics/service-authorization-uma-authz-process.adoc[leveloffset=+3]

authorization_services/topics/service-authorization-obtaining-permission.adoc

@@ -65,7 +65,7 @@ curl -X POST \
   http://${host}:${port}/auth/realms/${realm}/protocol/openid-connect/token \
   -H "Authorization: Bearer ${access_token}" \
   --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
-  --data "audience=${resource_server_id}" \
+  --data "audience={resource_server_client_id}" \
   --data "permission=Resource A#Scope A" \
   --data "permission=Resource B#Scope B"
 ```
@@ -76,7 +76,8 @@ Example of a authorization request when a client is seeking access to any resour
 curl -X POST \
   http://${host}:${port}/auth/realms/${realm}/protocol/openid-connect/token \
   -H "Authorization: Bearer ${access_token}" \
-  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket"
+  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
+  --data "audience={resource_server_client_id}"
 ```
 
 Example of an authorization request when a client is seeking access to a UMA protected resource after receiving a permission ticket from

authorization_services/topics/service-authorization-pushing-claims.adoc

@@ -0,0 +1,33 @@
+[[_service_pushing_claims]]
+= Pushing Claims
+
+When obtaining permissions from the server you can push arbitrary claims in order to have these
+claims available to your policies when evaluating permissions.
+
+If you are obtaining permissions from the server *without* using a permission ticket (UMA flow), you can send
+an authorization request to the token endpoint as follows:
+
+```bash
+curl -X POST \
+  http://${host}:${port}/auth/realms/${realm}/protocol/openid-connect/token \
+  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
+  --data "claim_token=ewogICAib3JnYW5pemF0aW9uIjogWyJhY21lIl0KfQ==" \
+  --data "claim_token_format=urn:ietf:params:oauth:token-type:jwt" \
+  --data "client_id={resource_server_client_id}" \
+  --data "client_secret={resource_server_client_secret}" \
+  --data "audience={resource_server_client_id}"
+```
+
+The `claim_token` parameter expects a BASE64 encoded JSON with a format similar to the example below:
+
+```json
+{
+    "organization" : ["acme"]
+}
+```
+
+The format expects one or more claims where the value for each claim must be an array of strings.
+
+== Pushing Claims Using UMA
+
+For more details about how to push claims when using UMA and permission tickets, please take a look at <<_service_protection_permission_api_papi, Permission API>>

authorization_services/topics/service-protection-permission-api-papi.adoc

@@ -29,3 +29,45 @@ Client wise, a permission ticket has also important aspects that its worthy to h
 
 These are just some of the benefits brought by UMA where other aspects of UMA are strongly based on permission tickets, specially regarding
 privacy and user controlled access to their resources.
+
+== Creating Permission Ticket
+
+To create a permission ticket, send an HTTP POST request as follows:
+
+```bash
+curl -X POST \
+  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission \
+  -H 'Authorization: Bearer '$pat \
+  -H 'Content-Type: application/json' \
+  -d '[
+  {
+    "resource_id": "{resource_id}",
+    "resource_scopes": [
+      "view"
+    ]
+  }
+]'
+```
+
+When creating tickets you can also push arbitrary claims and associate these claims with the ticket:
+
+```bash
+curl -X POST \
+  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission \
+  -H 'Authorization: Bearer '$pat \
+  -H 'Content-Type: application/json' \
+  -d '[
+  {
+    "resource_id": "{resource_id}",
+    "resource_scopes": [
+      "view"
+    ],
+    "claims": {
+        "organization": ["acme"]
+    }
+  }
+]'
+```
+
+Where these claims will be available to your policies when evaluating permissions for the resource and scope(s) associated
+with the permission ticket.

tests/src/test/resources/ignored-variables

@@ -17,4 +17,5 @@ keycloak.access_token['/custom_claim/0']
 keycloak.access_token
 keycloak.access_token['/sub']
 keycloak.access_token['/preferred_username']
-keycloak.access_token['/custom_claim']
+keycloak.access_token['/custom_claim']
+resource_id