How to Manage UMA Resources

UMA resource servers register resources with the resource owner's chosen authorization server. Registered resources can then be protected, and are available for user-created policies.

AM supports optional system labels when registering resources to help resource owners with organization. For information on labeling resources, see Managing UMA Labels.

AM provides the UMA resource_set REST endpoint, as documented in the OAuth 2.0 Resource Registration specification, to let UMA resource servers register and manage resources.

The endpoint requires a protection API token (PAT), which is an OAuth 2.0 access token with a scope of uma_protection. A resource server must acquire a PAT in order to use the resource set endpoint.

To Acquire a PAT

This example assumes that a confidential client called UMA-Resource-Server is registered in AM with, at least, the following configuration:

Client Secret: password
Scopes: uma_protection
Grant Types: Resource Owner Password Credentials
This example uses the Resource Owner Password Credentials grant, but you can use any grant type except the Client Credentials one to obtain the PAT.

The example also assumes that an identity for the resource owner,alice, exists in AM.

Perform the following steps to acquire a PAT on behalf of the resource owner>:

Send a POST request to the OAuth 2.0 access_token endpoint. The following example uses the Resource Owner Password Credentials grant:
```
$ curl \
--request POST \
--data 'grant_type=password' \
--data 'scope=uma_protection' \
--data 'username=alice' \
--data 'password=Ch4ng31t' \
--data 'client_id=UMA-Resource-Server' \
--data 'client_secret=password' \
https://openam.example.com:8443/openam/oauth2/realms/root/access_token
    {
    "access_token": "057ad16f-7dba-4049-9f34-e609d230d43a",
    "refresh_token": "340f82a4-9aa9-471c-ac42-f0ca1809c82b",
    "scope": "uma_protection",
    "token_type": "Bearer",
    "expires_in": 4999
}
```
The value returned in access_token is the Protection API Token, or PAT Bearer token.
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.

After acquiring a PAT, use the UMA resource_set REST endpoint for the following operations:

To Register an UMA Resource (REST)

Create a POST request to the UMA resource_set endpoint, including the PAT bearer token in an Authorization header.

The following example uses a resource owner's PAT bearer token to register a photo album resource and a pair of system labels in a realm named subrealm:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
--header "Accept-API-Version: resource=1.0" \
--data \
'{
    "name" : "Photo Album",
    "icon_uri" : "http://photoz.example.com/icons/flower.png",
    "resource_scopes" : [
        "edit",
        "view",
        "http://photoz.example.com/dev/scopes/print"
    ],
    "labels" : [
        "3D",
        "VIP"
    ],
    "type" : "http://photoz.example.com/dev/rtypes/photoalbum"
}' \
https://openam.example.com:8443/openam/uma/realms/root/resource_set
{
    "_id": "126615ba-b7fd-4660-b281-bae81aa45f7c0",
    "user_access_policy_uri": "https://openam.example.com:8443/openam/XUI/?realm=/#uma/share/126615ba-b7fd-4660-b281-bae81aa45f7c0"
}

To List Registered UMA Resources (REST)

Create a GET request to the UMA resource_set endpoint, including the PAT bearer token in an Authorization header.
The following example uses a PAT bearer token to list the registered resources in a realm named subrealm:
```
$ curl \
--header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/uma/realms/root/resource_set
{
    "126615ba-b7fd-4660-b281-bae81aa45f7c0",
    "3a2fe6d5-67c8-4a5a-83fb-09734f1dd5b10",
    "8ed24623-fcb5-46b8-9a64-18ee1b9b7d5d0"
}
```
On success, an array of the registered resource IDs is returned. Use the ID to identify a resource in the following procedures:

To Read an UMA Resource (REST)

Create a GET request to the UMA resource_set endpoint, including the PAT bearer token in an Authorization header.

Note

You must provide the ID of the resource to read, specified at the end of the request, as follows: https://openam.example.com:8443/openam/uma/realms/root/resource_set/resource_set_ID.

The following example uses a PAT bearer token and a resource ID to read a specific resource in a realm named subrealm:

$ curl \
--header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
https://openam.example.com:8443/openam/uma/realms/root/resource_set/126615ba-b7fd-4660-b281-bae81aa45f7c0
{
    "resource_scopes": [
        "read",
        "view",
        "http://photoz.example.com/dev/scopes/print"
    ],
    "name": "Photo Album",
    "_id": "126615ba-b7fd-4660-b281-bae81aa45f7c0",
    "type": "https//www.example.com/rsets/photoalbum",
    "icon_uri": "http://www.example.com/icons/flower.png",
    "labels": [
        "VIP",
        "3D"
    ],
    "user_access_policy_uri":
        "https://openam.example.com:8443/openam/XUI/?realm=/#uma/share/126615ba-b7fd-4660-b281-bae81aa45f7c0"
}

On success, AM returns an HTTP 200 OK status code as well as a representation of the resource in the JSON body of the response.

If the resource ID does not exist, AM returns an HTTP 404 Not Found status code, as follows:

{
  "error": "not_found",
  "error_description":
  "Resource set corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found"
}

To Update an UMA Resource (REST)

This example updates the UMA policy for user bob with the delete scope. The registered user for UMA in this example is alice who has permission to update the policy using their own SSO token in the header.

Before you can read or update a resource, you have to acquire a PAT token on behalf of the resource owner.

Add the new policy action delete to the appropriate resource type.

$ curl \
'http://openam.example.com:8080/openam/json/resourcetypes/630a0d-4d86-4b7e-848-3bf7dda7d220' \
--request PUT \
--header 'Accept-API-Version: protocol=1.0,resource=1.0' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723"
--data-raw '{"uuid":"63d10a0d-4d86-4b7e-8548-3bf70dda7d220", \
  "description":"Dynamically created resource type for the UMA resource set. \
       Used to find all Policy Engine Policies that make up an UMA Policy", \
  "actions": \
       {"download":true, \
        "view":true, \
        "comment":true, \
        "delete":true}, \
  }'

Send a PUT request to the UMA resource_set endpoint. Include the following:

A PAT bearer token in a header named Authorization
Any new or changed parameters in the existing values.
The ID of the resource to update, specified at the end of the request. Example: https://openam.example.com:8080/openam/uma/realms/root/resource_set/resource_set_ID.

The following example uses a PAT bearer token and a resource ID add the delete scope to a realm resource:

$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match: *" \
--data \
'{
    "policyId": "5c322250-a39b-455e-8413-33c3f8a876e00",
    "permissions":
       [
         {
           "subject": "bob",
           "scopes": [
              "view",
              "comment",
              "download",
              "delete"
           ]
        }
       ]
}' \
http://openam.example.com:8080/openam/json/realms/root/users/alice/uma/policies/5c322250-a39b-455e-8413-33c3f8a876e00
{
  "_id": "63d10a0d-4d86-4b7e-8548-3bf70dda7d220",
  "_rev": "-92235058",
  "policyId": "63d10a0d-4d86-4b7e-8548-3bf70dda7d220",
  "permissions": [
    {
      "subject": "bob",
      "scopes": [
        "download",
        "delete",
        "view",
        "comment"
      ]
    }
  ]
}

To Delete an UMA Resource (REST)

Create a DELETE request to the UMA resource_set endpoint, including the PAT bearer token in a header named Authorization.
Provide the ID of the resource to delete, specified at the end of the request as follows: https://openam.example.com:8443/openam/uma/realms/root/resource_set/resource_set_ID
```
$ curl \
--request DELETE \
--header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/uma/realms/root/resource_set/126615ba-b7fd-4660-b281-bae81aa45f7c0
{}
```
On success, AM returns an HTTP 204 No Content status code as well as an empty response body.
If the resource ID does not exist, AM returns an HTTP 404 Not Found status code, as follows:
```
{
    "error": "not_found",
    "error_description":
        "Resource set corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found"
}
```