Managing 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 requires that a resource is registered to the user in the URL. For information on registering resource sets, see Managing UMA Resources.

Once a resource is registered to the user, use the /json/users/{user}/uma/policies/ REST endpoint for managing UMA resource policies.

To create an UMA policy, see "To Create an UMA Policy".

To Read an UMA Policy

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.

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, an HTTP 200 OK status code is returned, 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 an UMA Policy

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.

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, an HTTP 200 OK status code is returned, 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, an HTTP 400 Bad Request status code is returned, 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, an HTTP 400 Bad Request status code is returned, for example:

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

To Delete an UMA Policy

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.

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, an HTTP 200 OK status code is returned, 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 UMA Policies

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.

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, an HTTP 200 OK status code is returned, 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, an HTTP 500 Server Error is returned, as follows:
```
{
    "code": 500,
    "reason": "Internal Server Error",
    "message": "'/badField' not queryable"
}
```