How to Manage UMA Policies
UMA authorization servers must manage the resource owner's authorization policies, so that registered resources can be protected.
The /json/users/{user}/uma/policies/
REST endpoint lets users create and manage authorization policies.
Important
UMA policies are designed to be user-managed, and not manipulated by AM administrators, using the standard policy
endpoints. If AM administrators manipulate UMA policies directly, they risk breaking the integrity of the UMA security model.
Managing UMA policies with the REST endpoint requires that a resource is registered to the user in the URL. For information on registering resource sets, see "/uma/resource_set".
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.
Note
Only the resource owner can create a policy to protect a resource. Administrator users, such as amAdmin
, cannot create policies on behalf of a resource owner.
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 theiPlanetDirectoryPro
cookie when creating the policy below.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 ofpolicyId
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 userbob
:$
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.
Tip
The ID used for a policy is always identical to the ID of the resource it protects.
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 theiPlanetDirectoryPro
cookie in the next step.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 isdemo
.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.
Tip
The ID used for a policy is always identical to the ID of the resource it protects.
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 theiPlanetDirectoryPro
cookie in the next step.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 ofpolicyId
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.
Tip
The ID used for a policy is always identical to the ID of the resource it protects.
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 theiPlanetDirectoryPro
cookie in the next step.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.
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 theiPlanetDirectoryPro
cookie in the next step.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
andname
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" }