How to Manage UMA Policies

To create a policy, the resource owner must be logged in to the authorization server, have an SSO token issued to them, and must also have the resource ID to be protected.

1. Log in as the resource owner to obtain an SSO token:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: alice" \
   --header "X-OpenAM-Password: Ch4ng31t" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
   {
       "tokenId":"AQIC5wM2LY4S...Q4MTE4NTA2*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

   The value returned in the tokenId element is the SSO token of the resource owner, Alice. Use this value as the contents of the iPlanetDirectoryPro cookie when creating the policy below.

2. Send an HTTP PUT request to the UMA policy endpoint or to the user policy endpoint. Include the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource ID as the value of policyId in the body, and also in the URI.

   Example 1: UMA Policy Endpoint

   This example uses the policy owner's SSO token (iPlanetDirectoryPro cookie). The command below creates a policy to share a resource belonging to user alice with user bob:

   
   

   $ curl \
   --request PUT \
   --header "Accept-API-Version: resource=1.0" \
   --header "Cache-Control: no-cache" \
   --header "Content-Type: application/json" \                 
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --header "If-None-Match: *" \
   --data '{                                                
       "policyId": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
       "permissions":
       [
           {
               "subject": "bob",
               "scopes": [
                   "view",
                   "comment"
               ]
           }
       ]
   }' \
   https://openam.example.com:8443/openam/json/realms/root/users/alice/uma/policies/0d7790de-9066-4bb6-8e81-25b6f9d0b8853
        {                                              
       "_id": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
       "_rev": "-1985914901"
   }

   	Specify the SSO token of the resource owner. Administrative users such as amAdmin cannot create UMA resource policies on behalf of a resource owner.
   	Specify the ID of the registered resource that this policy will protect. The same resource ID must also be included in the URI of the REST call. See "To Register an UMA Resource (REST)".
   	Note that the returned _id value of the new policy set is identical to the ID of the registered resource.

   On success, AM returns an HTTP 201 Created status code with the ID of the created policy.

   If the permissions are not correct, AM returns an HTTP 400 Bad Request status. For example:

   {
       "code": 400,
       "reason": "Bad Request",
       "message": "Invalid UMA policy permission. Missing required attribute, 'subject'."
   }

   Example 2: User Policy Endpoint

   Using the user policy endpoint gives more control over how you define the policy. For example, you have more flexibility in using resource owner names or policy names that include special characters.

   You can use this endpoint if you have implemented your own UI or other interface for creating UMA policies. You'll have to manually manage any policies you create in this way.

   $ curl \
   --request PUT \
   --header "-API-Version: protocol=1.0,resource=1.0" \
   --header "Content-Type: application/json" \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --header "If-None-Match: *" \
   --data '{
   	"resources":[
         "uma://02f08d5e-396e-4d90-b151-0a09ff836c021"
      ],
      "applicationName":"umaresourceserver",
      "actionValues":{
         "read":true
      },
      "subject":{
         "type":"AuthenticatedUsers"
      }
   }' \
   https://openam.example.com:8443/openam/json/users/alice/policies/test123

   
   

To read a policy, the resource owner or an administrator user must be logged in to the authorization server and have an SSO token issued to them. The policy ID to read must also be known.

1. Log in as the resource owner to obtain an SSO token:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: alice" \
   --header "X-OpenAM-Password: Ch4ng31t" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
   {
       "tokenId":"AQIC5wM2LY4S...Q4MTE4NTA2*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

   The value returned in the tokenId element is the SSO token of the resource owner, Alice. Use this value as the contents of the iPlanetDirectoryPro cookie in the next step.

2. Create a GET request to the UMA policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource ID as part of the URL.

   Note

   The SSO token must have been issued to the user specified in the URL, or to an administrative user such as amAdmin. In this example, the user is demo.

   The following example uses an SSO token to read a specific policy with ID 43225628-4c5b-4206-b7cc-5164da81decd0 belonging to user demo:

   $ curl \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --header "Accept-API-Version: resource=1.0" \
   https://openam.example.com:8443/openam/json/realms/root/users/demo\
   /uma/policies/0d7790de-9066-4bb6-8e81-25b6f9d0b8853
   {
       "_id": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
       "_rev": "1444644662",
       "policyId": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
       "name": "Photo Album",
       "permissions": [
           {
               "subject": "bob",
               "scopes": [
                   "view",
                   "comment"
               ]
           }
       ]
   }

   On success, AM returns an HTTP 200 OK status code with a JSON body representing the policy.

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

   {
       "code": 404,
       "reason": "Not Found",
       "message": "UMA Policy not found, 43225628-4c5b-4206-b7cc-5164da81decd0"
   }

To update a policy, the resource owner or an administrator user must be logged in to the authorization server and have an SSO token issued to them. The policy ID to read must also be known.

1. Log in as the resource owner to obtain an SSO token:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: alice" \
   --header "X-OpenAM-Password: Ch4ng31t" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
   {
       "tokenId":"AQIC5wM2LY4S...Q4MTE4NTA2*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

   The value returned in the tokenId element is the SSO token of the resource owner, Alice. Use this value as the contents of the iPlanetDirectoryPro cookie in the next step.

2. Create a PUT request to the UMA policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource ID as both the value of policyId in the body and also as part of the URL.

   Note

   The SSO token must have been issued to the user specified in the URL. In this example, the user is demo.

   The following example uses an SSO token to update a policy with ID 0d7790de-9066-4bb6-8e81-25b6f9d0b8853 belonging to user demo with an additional subject, chris:

   $ curl \
   --request PUT \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --header "Content-Type: application/json" \
   --header "If-Match: *" \
   --header "Accept-API-Version: resource=1.0" \
   --data \
   '{
       "policyId": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
       "permissions":
       [
           {
               "subject": "bob",
               "scopes": [
                   "view",
                   "comment"
               ]
           },
           {
               "subject": "chris",
               "scopes": [
                   "comment"
               ]
           }
       ]
   }' \
   https://openam.example.com:8443/openam/json/realms/root/users/demo\
   /uma/policies/0d7790de-9066-4bb6-8e81-25b6f9d0b8853
   {
       "_id": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
       "_rev": "-1844449592",
       "policyId": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
       "permissions": [
           {
               "subject": "bob",
               "scopes": [
                   "view",
                   "comment"
               ]
           },
           {
               "subject": "chris",
               "scopes": [
                   "view"
               ]
           }
       ]
   }

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

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

   {
       "code": 404,
       "reason": "Not Found",
       "message": "UMA Policy not found, 43225628-4c5b-4206-b7cc-5164da81decd0"
   }

   If the permissions are not correct, AM returns an HTTP 400 Bad Request status code. For example:

   {
       "code": 400,
       "reason": "Bad Request",
       "message": "Invalid UMA policy permission. Missing required attribute, 'subject'."
   }

   If the policy ID in the URL does not match the policy ID used in the sent JSON body, AM returns an HTTP 400 Bad Request status code. For example:

   {
       "code": 400,
       "reason": "Bad Request",
       "message": "Policy ID does not match policy ID in the body."
   }

To delete a policy, the resource owner or an administrator user must be logged in to the authorization server and have an SSO token issued to them. The policy ID to read must also be known.

1. Log in as the resource owner to obtain an SSO token:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: alice" \
   --header "X-OpenAM-Password: Ch4ng31t" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
   {
       "tokenId":"AQIC5wM2LY4S...Q4MTE4NTA2*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

   The value returned in the tokenId element is the SSO token of the resource owner, Alice. Use this value as the contents of the iPlanetDirectoryPro cookie in the next step.

2. Create a DELETE request to the UMA policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource ID as part of the URL.

   Note

   The SSO token must have been issued to the user specified in the URL. In this example, the user is demo.

   The following example uses an SSO token to delete a policy with ID 0d7790de-9066-4bb6-8e81-25b6f9d0b8853 belonging to user demo:

   $ curl \
   --request DELETE \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --header "Accept-API-Version: resource=1.0" \
   https://openam.example.com:8443/openam/json/realms/root/realms/root/users/demo\
   /json/policies/0d7790de-9066-4bb6-8e81-25b6f9d0b8853
   {}

   On success, AM returns an HTTP 200 OK status code with an empty JSON body as the response.

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

   {
       "code": 404,
       "reason": "Not Found",
       "message": "UMA Policy not found, 43225628-4c5b-4206-b7cc-5164da81decd0"
   }

To query policies, the resource owner or an administrator user must be logged in to the authorization server and have an SSO token issued to them.

1. Log in as the resource owner to obtain an SSO token:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: alice" \
   --header "X-OpenAM-Password: Ch4ng31t" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
   {
       "tokenId":"AQIC5wM2LY4S...Q4MTE4NTA2*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

   The value returned in the tokenId element is the SSO token of the resource owner, Alice. Use this value as the contents of the iPlanetDirectoryPro cookie in the next step.

2. Create a GET request to the UMA policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro).

   Note

   The SSO token must have been issued to the user specified in the URL, or to an administrative user such as amAdmin.

   In this example, the user is demo.

   Use the following query string parameters to affect the returned results:

   _sortKeys=[+-]field[,field...]

   Sort the results returned, where field represents a field in the JSON policy objects returned.

   For UMA policies, only the policyId and name fields can be sorted.

   Optionally, use the + prefix to sort in ascending order (the default), or - to sort in descending order.

   _pageSize=integer

   Limit the number of results returned.

   _pagedResultsOffset=integer

   Start the returned results from the specified index.

   _queryFilter

   The _queryFilter parameter can take true to match every policy, false to match no policies, or a filter of the following form to match field values: field operator value where field represents the field name, operator is the operator code, value is the value to match, and the entire filter is URL-encoded. Only the equals (eq) operator is supported by the /uma/policies endpoint.

   The field value can take the following values:

   • resourceServer - the resource server that created the resource.

   • permissions/subject - the list of subjects that are assigned scopes in the policy.

   Filters can be composed of multiple expressions by a using boolean operator AND, and by using parentheses, (expression), to group expressions.

   Note

   You must URL-encode the filter expression in _queryFilter=filter. So, for example, the following filter:

   resourceServer eq "UMA-Resource-Server" AND permissions/subject eq "bob"

   When URL-encoded becomes:

   resourceServer+eq+%22UMA-Resource-Server%22+AND+permissions%2Fsubject+eq+%22bob%22

   The following example uses an SSO token to query the policies belonging to user demo, which have a subject bob in the permissions:

   $ curl \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --header "Accept-API-Version: resource=1.0" \
   --get \
   --data-urlencode '_sortKeys=policyId,name' \
   --data-urlencode '_pageSize=1' \
   --data-urlencode '_pagedResultsOffset=0' \
   --data-urlencode \
   '_queryFilter=permissions/subject eq "bob"' \
   https://openam.example.com:8443/openam/json/realms/root/users/demo/uma/policies
   {
       "result": [
           {
               "_id": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
               "policyId": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853",
               "name": "Photo Album",
               "permissions": [
                   {
                       "subject": "bob",
                       "scopes": [
                           "view",
                           "comment"
                       ]
                   },
                   {
                       "subject": "chris",
                       "scopes": [
                           "view"
                       ]
                   }
               ]
           }
       ],
       "resultCount": 1,
       "pagedResultsCookie": null,
       "remainingPagedResults": 0
   }

   On success, AM returns an HTTP 200 OK status code with a JSON body representing the policies that match the query.

   If the query is not formatted correctly, for example, an incorrect field is used in the _queryFilter, AM returns an HTTP 500 Server Error as follows:

   {
       "code": 500,
       "reason": "Internal Server Error",
       "message": "'/badField' not queryable"
   }

1. Log in to AM. Your user profile page appears.

2. On the Shares menu, click Resources. A list of the resources you own appears.

   The Resources Page when Logged In

   
   
   

3. To share a resource, click the name of the resource to open the resource details page, and then click the Share button.

   On the Share the resource form:

   1. Enter the username of the user with whom to share the resource.

   2. From the Select Permission drop-down list, choose the permissions to assign to the user for the selected resource.

   3. Click Share.

      Sharing an UMA Resource

      
      
      

   4. Repeat these steps to share the resources with additional users.

      Note

      AM creates a policy set containing a policy representing the resources and identities specified by the resource owner sharing their resources.

      These policies appear in the AM console as read-only, and cannot be edited by administrative users such as amAdmin. They can, however, be viewed and deleted.

4. When finished, click Close.