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>:

  • Create 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)
  • Create a PUT request to the UMA resource_set endpoint, including the PAT bearer token in a header named Authorization, and any new or changed parameters as part of a complete replacement of the existing values.

    Note

    You must provide the ID of the resource to update, 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 update a specific resource in a realm named subrealmwith an additional delete resource scope:

    $ curl \
    --request PUT \
    --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" : [
            "delete",
            "edit",
            "view",
            "http://photoz.example.com/dev/scopes/print"
        ],
        "labels" : [
            "3D",
            "VIP"
        ],
        "type" : "http://photoz.example.com/dev/rsets/photoalbum"
    }' \
    https://openam.example.com:8443/openam/uma/realms/root/resource_set/126615ba-b7fd-4660-b281-bae81aa45f7c0
    {
        "_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"
    }

    On success, AM returns an HTTP 200 OK status code with the resource ID, and a user access policy URI that the resource owner can visit in order to manage access to the resource.

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

    {
        "error": "not_found",
        "error_description":
            "ResourceSet corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found"
    }
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"
    }
Read a different version of :