keycloak-scim/topics/service/entitlement/entitlement-api-aapi.adoc

== Requesting Entitlements

Client applications can use a specific endpoint to obtain a special security token called *Requesting Party Token* or *RPT*.
This token consists of all the entitlements(or permissions) for an user as a result of the evaluation of the permissions and authorization policies associated with the resource(s) being requested.
With an RPT in hands, client applications can gain access to protected resources at the resource server.

```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement
```

=== Obtaining Entitlements

The easiest way to obtain entitlements for a specific user is using an HTTP GET request.

```bash
curl -X GET \
    -H "Authorization: Bearer ${EAT}" \
    "http://localhost:8080/auth/realms/hello-world-authz/authz/entitlement/${resource_server_id}"
```

[NOTE]
When asking for entitlements using this endpoint, you need to provide the EAT (as a bearer token) representing user's identity and his consent to access authorization data on his behalf.

Where *${resource_server_id}* is the *client_id* registered with the client application acting as a resource server.

As a result, you'll get a response from the server as follows:

```json
{
  "rpt": ${RPT}
}
```

When using this method to obtain entitlements, the server is going to respond the requesting client with *all* entitlements for an user, based on the evaluation of the permissions and
authorization policies associated with all resources managed by the resource server.

=== Obtaining Entitlements for a Specific Set of Resources

The entitlements endpoint also allows you to obtain user's entitlements for a set of one or more resources.

```bash
curl -X POST -H "Authorization: Bearer ${EAT}" -d '{
    "permissions" : [
        {
            "resource_set_name" : "Hello World Resource"
        }
    ]
}' "http://localhost:8080/auth/realms/hello-world-authz/authz/entitlement/hello-world-authz-service"
```

As a result, you'll get a response from the server as follows:

```json
{
  "rpt": ${RPT}
}
```

Unlink the GET version, the server is going to respond with a RPT holding the permissions granted during the evaluation of the permissions and authorization policies
 associated with the resources being requested.

When asking for entitlements you can also specify the scopes you want to have access:

```bash
curl -X POST -H "Authorization: Bearer ${EAT}" -d '{
    "permissions" : [
        {
            "resource_set_name" : "Hello World Resource",
            "scopes" : [
                "urn:my-app.com:scopes:view"
            ]
        }
    ]
}' "http://localhost:8080/auth/realms/hello-world-authz/authz/entitlement/hello-world-authz-service"
```

=== Requesting Party Token or RPT

A RPT is basically a https://tools.ietf.org/html/rfc7519[JSON Web Token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON Web Signature (JWS)].
Its lifetime is the same as with the OAuth2 access token (EAT) that was used to obtain it.

When you decode a RPT you may see something like that:

```json
{
  "permissions": [
    {
      "resource_set_id": "152251e6-f4cf-4464-8d91-f1b7960fa5fc",
      "resource_set_name": "Hello World Resource"
      "scopes" : [
        "urn:my-app.com:scopes:view"
      ]
    }
  ],
  "accessToken": ${EAT},
  "jti": "d6109a09-78fd-4998-bf89-95730dfd0892-1464906679405",
  "exp": 1464906971,
  "nbf": 0,
  "iat": 1464906671,
  "sub": "f1888f4d-5172-4359-be0c-af338505d86c",
  "typ": "kc_ett",
  "azp": "hello-world-authz-service"
}
```

The *permissions* claim consists of all the permissions granted by the server. There is also a *accessToken* property holding the AAT that was used to issue the RPT.