Managing 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. For more information, see "To Acquire a PAT".

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

To Register an UMA Resource

To register a resource, the resource server must first acquire a PAT token on behalf of the resource owner, as described in "To Acquire a PAT".

Once you have the PAT bearer token, you can access the UMA resource_set endpoint to register resources, as shown in the following steps.

  • 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

To list the resources registered to a user, you must first acquire a PAT token as that user, as described in "To Acquire a PAT".

Once you have the PAT token, you can access the UMA resource_set endpoint to list resources, as shown below:

  • 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

To read a resource, you must first acquire a PAT token on behalf of the resource owner, as described in "To Acquire a PAT".

Once you have the PAT token, you can access the UMA resource_set endpoint to read resources, as shown below:

  • 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, an HTTP 200 OK status code is returned, as well as a representation of the resource in the JSON body of the response.

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

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

To read a resource, you must first acquire a PAT token on behalf of the resource owner, as described in "To Acquire a PAT".

Once you have the PAT token, you can access the UMA resource_set endpoint to update resources, as shown below:

  • 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, an HTTP 200 OK status code is returned, 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, an HTTP 404 Not Found status code is returned, as follows:

    {
        "error": "not_found",
        "error_description":
            "ResourceSet corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found"
    }
To Delete an UMA Resource

To delete a resource, you must first acquire a PAT token, as described in "To Acquire a PAT".

Once you have the PAT token, you can access the UMA resource_set endpoint to delete resources, as shown below:

  • 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, an HTTP 204 No Content status code is returned as well as an empty response body.

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

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