Managing UMA Resources

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 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 Update an UMA Resource"

  • "To Delete 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"
  }

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 token on behalf of the resource owner. See "To Acquire a PAT".

2. 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}, \
     }'

3. 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 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"
  }