service-authorization-obtaining-permission.adoc

Obtaining Permissions

To obtain permissions from {project_name} you send an authorization request to the token endpoint. As a result, {project_name} will evaluate all policies associated with the resource(s) and scope(s) being requested and issue an RPT with all permissions granted by the server.

Clients are allowed to send authorization requests to the token endpoint using the following parameters:

• grant_type

  This parameter is required. Must be urn:ietf:params:oauth:grant-type:uma-ticket.

• ticket

  This parameter is optional. The most recent permission ticket received by the client as part of the UMA authorization process.

• claim_token

  This parameter is optional. A string representing additional claims that should be considered by the server when evaluating permissions for the resource(s) and scope(s) being requested. This parameter allows clients to push claims to {project_name}. For more details about all supported token formats see claim_token_format parameter.

• claim_token_format

  This parameter is optional. A string indicating the format of the token specified in the claim_token parameter. {project_name} supports two token formats: urn:ietf:params:oauth:token-type:jwt and https://openid.net/specs/openid-connect-core-1_0.html#IDToken. The urn:ietf:params:oauth:token-type:jwt format indicates that the claim_token parameter references an access token. The https://openid.net/specs/openid-connect-core-1_0.html#IDToken indicates that the claim_token parameter references an OpenID Connect ID Token.

• rpt

  This parameter is optional. A previously issued RPT which permissions should also be evaluated and added in a new one. This parameter allows clients in possession of an RPT to perform incremental authorization where permissions are added on demand.

• permission

  This parameter is optional. A string representing a set of one or more resources and scopes the client is seeking access. This parameter can be defined multiple times in order to request permission for multiple resource and scopes. This parameter is an extension to urn:ietf:params:oauth:grant-type:uma-ticket grant type in order to allow clients to send authorization requests without a permission ticket. The format of the string must be: RESOURCE_ID#SCOPE_ID. For instance: Resource A#Scope A, Resource A#Scope A, Scope B, Scope C, Resource A, #Scope A.

• audience

  This parameter is optional. The client identifier of the resource server to which the client is seeking access. This parameter is mandatory in case the permission parameter is defined. It serves as a hint to {project_name} to indicate the context in which permissions should be evaluated.

• response_include_resource_name

  This parameter is optional. A boolean value indicating to the server whether resource names should be included in the RPT’s permissions. If false, only the resource identifier is included.

• response_permissions_limit

  This parameter is optional. An integer N that defines a limit for the amount of permissions an RPT can have. When used together with rpt parameter, only the last N requested permissions will be kept in the RPT.

• submit_request

  This parameter is optional. A boolean value indicating whether the server should create permission requests to the resources and scopes referenced by a permission ticket. This parameter only has effect if used together with the ticket parameter as part of a UMA authorization process.

• response_mode

  This parameter is optional. A string value indicating how the server should respond to authorization requests. This parameter is specially useful when you are mainly interested in either the overall decision or the permissions granted by the server, instead of a standard OAuth2 response. Possible values are:

  • decision

    Indicates that responses from the server should only represent the overall decision by returning a JSON with the following format:

    {
        'result': true
    }

    If the authorization request does not map to any permission, a 403 HTTP status code is returned instead.

  • permissions

    Indicates that responses from the server should contain any permission granted by the server by returning a JSON with the following format:

    [
        {
            'rsid': 'My Resource'
            'scopes': ['view', 'update']
        },
    
        ...
    ]

    If the authorization request does not map to any permission, a 403 HTTP status code is returned instead.

Example of a authorization request when a client is seeking access to two resources protected by a resource server.

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_client_id}" \
  --data "permission=Resource A#Scope A" \
  --data "permission=Resource B#Scope B"

Example of a authorization request when a client is seeking access to any resource and scope protected by a resource server.

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_client_id}"

Example of an authorization request when a client is seeking access to a UMA protected resource after receiving a permission ticket from the resource server as part of the authorization process:

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 "ticket=${permission_ticket}

If {project_name} assessment process results in issuance of permissions, it issues the RPT with which it has associated the permissions:

{project_name} responds to the client with the RPT

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "access_token": "${rpt}",
}

The response from the server is just like any other response from the token endpoint when using some other grant type. The RPT can be obtained from the access_token response parameter. If the client is not authorized, {project_name} responds with a 403 HTTP status code:

{project_name} denies the authorization request

HTTP/1.1 403 Forbidden
Content-Type: application/json
...
{
    "error": "access_denied",
    "error_description": "request_denied"
}