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 a *Requesting Party Token* or *RPT*.
This token consists of all the entitlements (or permissions) for a user as a result of the evaluation of the permissions and authorization policies associated with the resource(s) being requested.
With an RPT in hand, 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. For example, using curl:

```bash
curl -X GET \
    -H "Authorization: Bearer ${access_token}" \
    "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 access_token (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf.

In the curl example, *${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}
}
```

Using this method to obtain entitlements, the server will respond to the requesting client with *all* entitlements for a user, based on the evaluation of the permissions and
authorization policies associated with the resources managed by the resource server.

=== Obtaining Entitlements for a Specific Set of Resources

The entitlements endpoint also allows you to obtain a user's entitlements for a set of one or more resources. For example, using curl:

```bash
curl -X POST -H "Authorization: Bearer ${access_token}" -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}
}
```

Unlike the GET version, the server is going to respond with an 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. Using curl:

```bash
curl -X POST -H "Authorization: Bearer ${access_token}" -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 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)].
The token is built based on the access_token sent by the client during the authorization process.

When you decode a RPT, you will see a payload similar to the following:

```json
{
  "authorization": {
      "permissions": [
        {
          "resource_set_id": "d2fe9843-6462-4bfc-baba-b5787bb6e0e7",
          "resource_set_name": "Hello World Resource"
        }
      ]
  },
  "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"
}
```

From this token you can obtain all permissions granted by the server from the *permissions* claim.