From 3f051df3574f8489228df58e4975d17fc2b97d28 Mon Sep 17 00:00:00 2001 From: Pedro Igor Date: Mon, 5 Jun 2017 16:11:38 -0300 Subject: [PATCH] [KEYCLOAK-4992] - Allow clients to limit the number of permission in a RPT when using entitlements --- .../entitlement-request-metadata.adoc | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc b/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc index c38d1f98f4..ec9512d312 100755 --- a/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc +++ b/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc @@ -36,7 +36,30 @@ curl -X POST -H "Authorization: Bearer ${access_token}" -d '{ Clients can use ```include_resource_name``` to decide whether or not resource`s name should be included on each permission granted by the server. This option can be used to reduce the size of RPTs and optimize client-server communication. -By default, permissions in a RPT contain both the id and name of the resource that was granted for every single permission. This option is specially useful +By default, permissions in a RPT contain both the id and name of the resource that was granted by every single permission. This option is specially useful when the resource server is capable of map their resources only based on the resource`s id. +==== Limiting the number of permissions within a RPT + +.limit +```bash +curl -X POST -H "Authorization: Bearer ${access_token}" -d '{ + "metadata" : { + "limit" : 10 + }, + "permissions" : [ + ... + ] +}' "http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement/{client_id}" +``` +Clients can use ```limit``` to specify how many permissions they expected within a RPT returned by the server. The limit option works as follows: + +* If a request is sent *without* a previously issued RPT, only ```limit``` permissions will be returned based on the resources/scopes from the ```permissions``` claim. +* If a request is sent *with* a previously issued RPT, the permissions associated with the resources/scopes from the ```permissions``` claim take precedence where the permissions +from the previously issued RPT are only included if ```limit``` is not reached. In case there is enough room for permissions from a previously issued RPT, the server +will include the first permissions defined there. + +This option allows clients to control the size of RPTs and keep only last permissions granted by the server. It usually makes sense only in cases your client +is capable of sending previously issued RPTs while asking for new permissions (a.k.a.: incremental authorization). +