The UMA Grant Flow

The UMA grant flow grants a requesting party access token (RPT) to the requesting party to allow access to a resource.

A requesting party, using a client application, requests access to an UMA-protected resource (labeled 1 and 2 in the diagram above).
The resource server checks the existing token (3) and determines that the requesting party does not have the correct privileges to access the resource. The resource server returns a permission ticket (4) to the client.
The client uses the permission ticket and a claim token to send an RPT from AM (5 and 6).
AM makes a policy decision using the requested scopes, the scopes permitted in the registered resource, and the user-created policy, and if successful returns an RPT (7 and 8).
The client presents the RPT to the resource server (9), which must verify the token is valid using the AM introspection endpoint (10). If the RPT is confirmed to be valid and non-expired (10), the resource server can return the protected resource to the client for access by the requesting party (11).

To issue an RPT to a requesting party, run the following procedures:

UMA 2.0 Grant Flow

Task	Description
Create a permission ticket	"Create a Permission Ticket"
Gather claims to create a claim token	"Gather Claims"
Obtain an RPT	"Obtain an RPT"

Create a Permission Ticket

When the resource server receives a request for access to a resource, it contacts the authorization server to acquire a permission ticket. The permission ticket associates a request for a particular resource with the corresponding scopes. The PAT bearer token of the resource owner is used to map the request to the correct identity.

The permission ticket and the claim token are used to obtain a requesting party access token (RPT). A new permission ticket must be used for each attempt to acquire an RPT.

Send a POST request to the UMA permission_request endpoint:

$ curl -X POST \
--header 'authorization: Bearer 057ad16f-7dba-4049-9f34-e609d230d43a' \
--header 'cache-control: no-cache' \
--header 'content-type: application/json' \
--data '[
    {
        "resource_id" : "ef4d750e-3831-483b-b395-c6f059b5e15d0", 
        "resource_scopes" : ["download"]
    }
]' \
https://openam.example.com:8443/openam/uma/realms/root/permission_request
     {
    "ticket": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
               LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
               HA6Ly9vcGVuYW0uZGVmYXVsdC5leGFtcGxlLmNvbTo4MC9vcGVuYW0vb2F1dGgyIi
               wiaXQiOjAsImV4cCI6MTUwNzE0ODI2MiwidGlkIjoiZWY0ZDc1MGUtMzgzMS00ODN
               iLWIzOTUtYzZmMDU5YjVlMTVkMiIsImZvcmdlcm9jayI6eyJzaWciOiIzUylGOk1u
               N0N0dVlIZVpQVVtrMGZlajJmL2JAVDBYfWI4dH1hOEQmIn19.vi6RxLMxl5MiB1uK
               60P1yE2HIhWnF7CDFgz4agM5YAQ" 
}

	Use the PAT Bearer Token previously acquired on behalf of the resource owner. See "To Acquire a PAT".
	Specify the ID of the registered resource for which this permission ticket will maintain permission state information. See "Register an UMA Resource".
	The value returned in the `ticket` property is the permission ticket, which is used to obtain an RPT. See "Obtain an RPT".

Note

The default lifetime for an UMA permission ticket is 120 seconds. Attempting to obtain a requesting party token after the permission ticket has expired will fail with an error message as follows:

{
     "error_description": "The provided access grant is invalid, expired, or revoked.", "error": "invalid_grant"
     }

You can alter the default lifetime of a permission ticket by navigating to Realms > Realm Name > Services > UMA Provider, and editing the Permission Ticket Lifetime (seconds) property.

Gather Claims

The authorization server must gather claims from the requesting party to create a claim token.

Send a POST request to the OAuth 2.0 access_token endpoint. The value returned in the id_token property is the claim token required to obtain an RPT, along with the permission ticket acquired earlier:

$ curl -X POST \
--header 'authorization: Basic VW1hQ2xpZW50OnBhc3N3b3Jk' \
--header 'cache-control: no-cache' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=password' \
--data 'scope=openid' \
--data 'username=bob' \
--data 'password=password' \
https://openam.example.com:8443/openam/oauth2/realms/root/access_token
     {
  "access_token": "f09f55e5-5e9c-48fe-aeaa-d377de88e8e6",
  "refresh_token": "ee2d35f6-5819-4734-8b3e-9af77a545563",
  "scope": "openid",
  "id_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiJiL082T3ZWdjEreStXZ3JINVVpOVdUaW9MdDA
               9IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoiMWpodGpUQ0JmLWdKeDFUZGR
               EdFlIdyIsInN1YiI6ImJvYiIsImF1ZGl0VHJhY2tpbmdJZCI6IjBmZjAxNzQ0LW
               Y5ZDMtNGFhMi04NmU4LTcyNTJlYTUyMWQ4Yi04MDIiLCJpc3MiOiJodHRwOi8vb
               3BlbmFtLmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsInRv
               a2VuTmFtZSI6ImlkX3Rva2VuIiwiYXVkIjoiVW1hQ2xpZW50IiwidXBkYXRlZF9
               hdCI6IjE1MDcwODc5MDEiLCJhenAiOiJVbWFDbGllbnQiLCJhdXRoX3RpbWUiOj
               E1MDcwODgyNjcsInJlYWxtIjoiLyIsImV4cCI6MTUwNzE0ODI2NywidG9rZW5Ue
               XBlIjoiSldUVG9rZW4iLCJpYXQiOjE1MDcwODgyNjd9.aVEF0P0pSUsifl_aPuZ
               QwWxhv6CvqNEbK6_kDpat_u-gfwKZZRWmdvouLa9dNmGr33EQJY4LifCUHA_AKn
               048G3W6czBupC4TJESK4rDwKr2OXPQVzTrGNk25ix5Dw_BdngW-YJfnXmlSByKt
               ZmaYT7FGS0bdGMedtkypVpM6uZAQcc9JEmOlOCHF-l57NH88pOP7MkY9gszlGJi
               3cFEMHONTBB6-yroJyU-vaDJzWeCX3uGVqY8K3nUMqMguRSIkqrltabyX4CuKtN
               JlthJUEnX4mZFBNf7un7Qs3nx3BUAzclKjL2H1FNyD2a-zx3YOJ9Wm4kj_SlgTg
               FBznEB5A", 
  "token_type": "Bearer",
  "expires_in": 4999
}

	Authorize using the credentials of the UMA client. Use the client ID and client secret, separated by a colon character, for example `UmaClient:password`. Base64-encode the result. See "To Create an UMA Client Agent".
	The value returned in the `id_token` property is the claim token, which is used to obtain an RPT. See "Obtain an RPT".

Note

To use the Resource Owner Password Credentials grant type, as described in RFC 6749, the default authentication chain in the relevant realm must allow authentication using only a username and password, for example by using a DataStore module. Attempting to use the Resource Owner Password Credentials grant type with a chain that requires any additional input returns an HTTP 500 Server Error message.

Obtain an RPT

The requesting party makes a request using the permission ticket and the claim token, in exchange for a RPT.

Send a POST request to the OAuth 2.0 access_token endpoint. Make sure to include the permission ticket, ticket, and the claim_token. The following example results in an error description, indicating that "The client is not authorised to access the requested resource set." The authorization server sends a request to the resource owner to allow or deny access to the requesting party.

$ curl -X POST \
  --header 'authorization: Basic VW1hQ2xpZW50OnBhc3N3b3Jk' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:uma-ticket' \
  --data 'ticket=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
               LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
               HA6Ly9vcGVuYW0uZGVmYXVsdC5leG$' \
  --data 'scope=download' \
  --data 'claim_token=eyJ0eXAiOiJKV1QiLCJraWQiOiJiL082T3ZWdjEreStXZ3JINVVpOVdUaW9MdDA
                 9IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoieWExdHlyZFdBTTYwWGlfLU5
                 EUTc4ZyIsInN1YiI6ImJvYiIsImF1ZG$' \
  --data 'claim_token_format=https://openid.net/specs/openid-connect-core-1_0.html#IDToken' \
  https://openam.example.com:8443/openam/oauth2/realms/root/access_token
     {
  "ticket": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
             LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
             HA6Ly9vcGVuYW0uZGVmYXVsdC5leGFtcGxlLmNvbTo4MC9vcGVuYW0vb2F1dGgyIi
             wiaXQiOjEsImV4cCI6MTUwNzE0ODEzNSwidGlkIjoiNTkzNmExOGMtOGE2OC00YTI
             xLTliOGQtZWViNzIyOGEwMDY3MCIsImZvcmdlcm9jayI6eyJzaWciOiIqP2pMUEVV
             M3hYNm5RbU8-YXFXZ0d9aTJ1OjNnLlRrc2FKI3UpXnokIn19.a9JpfsXS09CNvr2B
             RtLDO-t4ZCnmrHr2h3auXPeJi3E",
  "error_description": "The client is not authorised to access the requested resource set. A request has been submitted to the resource owner requesting access to the resource",
  "error": "request_submitted"
}

	Authorize using the credentials of the UMA client. Use the username and password, separated by a colon character, for example, `UmaClient:password`, and base64-encode the result. See "To Create an UMA Client Agent".
	Specify the permission ticket acquired earlier. See "Create a Permission Ticket".
	Specify the claim token acquired earlier. See "Gather Claims".

Note

The default lifetime for an UMA permission ticket is 120 seconds. Attempting to obtain a requesting party token after the permission ticket has expired will fail with an error message as follows:

{
     "error_description": "The provided access grant is invalid, expired, or revoked.", "error": "invalid_grant"
     }

If the ticket has expired, obtain another by repeating the steps in "Create a Permission Ticket".

You can alter the default lifetime of a permission ticket by navigating to Realms > Realm Name > Services > UMA Provider, and editing the Permission Ticket Lifetime (seconds) property.

The resource owner, Alice, logs into AM to view the access request. She clicks Shares > Requests, and clicks Allow to grant read access to Bob, the requesting party.
Consent Screen Presented to the Resource Owner
Because each permission token can only be used once, request a new permission token by performing the steps in "Create a Permission Ticket".

Resubmit the previous POST request for the RPT, with the new permission ticket obtained in the previous step and the original claim token:

curl -X POST \
--header 'authorization: Basic VW1hQ2xpZW50OnBhc3N3b3Jk' \
--header 'cache-control: no-cache' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=urn:ietf:params:oauth:grant-type:uma-ticket' \
--data 'ticket=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
        LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
        HA6Ly9vcGVuYW0uZGVmYXVsdC5leG$' \
--data 'scope=download' \
--data 'claim_token=eyJ0eXAiOiJKV1QiLCJraWQiOiJiL082T3ZWdjEreStXZ3JINVVpOVdUaW9MdDA
        9IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoieWExdHlyZFdBTTYwWGlfLU5
        EUTc4ZyIsInN1YiI6ImJvYiIsImF1ZG$' \
--data 'claim_token_format=https://openid.net/specs/openid-connect-core-1_0.html#IDToken' \
https://openam.example.com:8443/openam/oauth2/realms/root/access_token
     {
    "access_token": "Aw4a92ZoKsjadWKw2d4Rmcjv7DM",
    "token_type": "Bearer",
    "expires_in": 3599
}

	Authorize using the same credentials of the UMA client as the first request for an RPT.
	Specify a refreshed permission ticket acquired earlier, otherwise you will receive a response such as: `The provided access grant is invalid, expired, or revoked`. See "Create a Permission Ticket".
	Specify the same claim token as the first request for an RPT.

The access_token is the RPT, which lets the requesting party access the resource through a client.

(Optional) You can use the /oauth2/introspect endpoint to inspect the properties of the RPT. Use the PAT issued to the resource owner for authenticating to the authorization server, and specify the RPT token in a query parameter named token, as follows:

$ curl --header 'authorization: Bearer 057ad16f-7dba-4049-9f34-e609d230d43a' \
'https://openam.example.com:8443/openam/oauth2/realms/root/introspect?token=Aw4a92ZoKsjadWKw2d4Rmcjv7DM'
    {
    "active": true,
    "permissions": [
        {
            "resource_id": "ef4d750e-3831-483b-b395-c6f059b5e15d0",
            "resource_scopes": [
                "download"
            ],
            "exp": 1522334692
        }
    ],
    "token_type": "access_token",
    "exp": 1522334692,
    "iss": "https://openam.example.com:8443/openam/oauth2"
}