--- title: UMA resources description: 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. component: pingam version: 8.1 page_id: pingam:uma:uma-resource-sets canonical_url: https://docs.pingidentity.com/pingam/8.1/uma/uma-resource-sets.html keywords: ["User-Managed Access (UMA)", "Resource Sets"] page_aliases: ["uma-guide:uma-resource-sets.adoc"] section_ids: acquire_a_pat_on_behalf_of_a_resource_owner: Acquire a PAT on behalf of a resource owner register-an-uma-resource-set: Register an UMA resource (REST) to-list-uma-resource-sets: List registered UMA resources (REST) read-an-uma-resource-set: Read an UMA resource (REST) update-an-uma-resource-set: Update an UMA resource (REST) delete-an-uma-resource-set: Delete an UMA resource (REST) --- # 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 [UMA labels](uma-manage-resource-set-labels.html). AM exposes the UMA `resource_set` REST endpoint, as documented in the [OAuth 2.0 Resource Registration](https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html) specification. This endpoint lets 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. ## Acquire a PAT on behalf of a resource owner This example assumes that a confidential client called *UMA-Resource-Server* is registered in AM with, at least, the following configuration: * **Client Secret**: `mySecret` * **Scopes**: `uma_protection` * **Grant Types**: `Resource Owner Password Credentials` The example uses the Resource Owner Password Credentials grant, but you can use any grant type to obtain the PAT, except the Client Credentials grant. The example also assumes that an identity for the resource owner,`alice`, exists in AM. 1. Send a POST request to the OAuth 2.0 `access_token` endpoint. This example uses the `Resource Owner Password Credentials` grant: ```bash $ 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=mySecret' \ "https://am.example.com:8443/am/oauth2/realms/root/realms/alpha/access_token" { "access_token": "oMsRVDXHYsWAC0KClr6dmX2_cIc", "scope": "uma_protection", "token_type": "Bearer", "expires_in": 3599 } ``` 2. The value returned in `access_token` is the Protection API Token, or PAT Bearer token. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To use the `Resource Owner Password Credentials` grant type, as described in [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3), the default authentication tree in the relevant realm must allow authentication using only a username and password. If you try to use the `Resource Owner Password Credentials` grant type with a tree that requests additional input, the server returns an HTTP `500 Server Error`. | After acquiring a PAT, use the UMA `resource_set` REST endpoint for the following operations: ## Register an UMA resource (REST) 1. 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`: ```bash $ 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://am.example.com:8443/am/uma/realms/root/realms/alpha/resource_set" { "_id": "126615ba-b7fd-4660-b281-bae81aa45f7c0", "user_access_policy_uri": "https://am.example.com:8443/am/XUI/?realm=/#uma/share/126615ba-b7fd-4660-b281-bae81aa45f7c0" } ``` ## List registered UMA resources (REST) 1. 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`: ```bash $ curl \ --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \ --header "Accept-API-Version: resource=1.0" \ "https://am.example.com:8443/am/uma/realms/root/realms/alpha/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: * [Read an UMA resource (REST)](#read-an-uma-resource-set) * [Update an UMA resource (REST)](#update-an-uma-resource-set) * [Delete an UMA resource (REST)](#delete-an-uma-resource-set) ## Read an UMA resource (REST) 1. Create a GET request to the UMA `resource_set` endpoint, including the PAT bearer token in an Authorization header. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You must provide the ID of the resource to read, specified at the end of the request, as follows: `https://am.example.com:8443/am/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`: ```bash $ curl \ --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \ "https://am.example.com:8443/am/uma/realms/root/realms/alpha/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://am.example.com:8443/am/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: ```json { "error": "not_found", "error_description": "Resource set corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found" } ``` ## 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. 1. Before you can read or update a resource, you have to [acquire a PAT](#to_acquire_a_pat) token on behalf of the resource owner. 2. Add the new policy action `delete` to the appropriate resource type. ```bash $ curl \ --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 '{"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 }, }' \ "https://am.example.com:8443/am/json/resourcetypes/630a0d-4d86-4b7e-848-3bf7dda7d220" ``` 3. Create 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://am.example.com:8443/am/uma/realms/root/resource_set/resource_set_ID`. The following example uses a PAT bearer token and a resource ID to add the `delete` scope to a realm resource. ```json 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" ] } ] }' \ "https://am.example.com:8443/am/json/realms/root/realms/alpha/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" ] } ] } ``` ## Delete an UMA resource (REST) 1. 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://am.example.com:8443/am/uma/realms/root/resource_set/resource_set_ID` ```bash $ curl \ --request DELETE \ --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \ --header "Accept-API-Version: resource=1.0" \ "https://am.example.com:8443/am/uma/realms/root/realms/alpha/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: ```json { "error": "not_found", "error_description": "Resource set corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found" } ```