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 ${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 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 ${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 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 ${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 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)].
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 something like that:

```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.