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.

UMA policies are designed to be user-managed and not manipulated by AM administrators, using the standard policy endpoints. If AM administrators use UMA policies directly, they risk breaking the integrity of the UMA security model.

To manage an UMA policy over REST, the resource must be registered to the user specified in the URL. For information on registering resource sets, refer to /uma/resource_set.

Create an UMA policy (REST)

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

Only the resource owner can create a policy to protect a resource. Administrative users, such as amAdmin, cannot create policies on behalf of a resource owner.

$ 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":"/alpha"
}

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 you create the policy.

Send a PUT request to the UMA policies endpoint.

Include the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro). Include the resource ID as the value of policyId in the body, and also in the URI.

This example uses the policy owner’s SSO token (iPlanetDirectoryPro cookie). The command 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*" \ (1)
--header "If-None-Match: *" \
--data '{
    "policyId": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853", (2)
    "permissions":
    [
        {
            "subject": "bob",
            "scopes": [
                "view",
                "comment"
            ]
        }
    ]
}' \
https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/alice/uma/policies/0d7790de-9066-4bb6-8e81-25b6f9d0b8853
{
    "_id": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853", (3)
    "_rev": "-1985914901"
}

1	Specify the SSO token of the resource owner. Administrative users such as `amAdmin` cannot create UMA resource policies on behalf of a resource owner.
2	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 Register an UMA Resource (REST).
3	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 error. For example:

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

For simplicity, this example uses "subject": "bob" to identify the user with whom the resource is shared. In a production deployment, the attribute that is used to identify the subject in an UMA policy should be something that can be independently verified as belonging to a specific user; for example, an email address.

Any self-service registration process or profile modification process should be configured to assure ownership of that identifier (by using an email address verification node, for example).

If your UMA deployment is not designed to verify the identity of the subject, you risk having UMA policies that can be "hijacked" by other users.

Read an UMA policy (REST)

To read a policy, the resource owner or an administrative 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.

The ID used for a policy is always identical to the ID of the resource it protects.

$ 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":"/alpha"
}

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.

Send 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.

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 alice.

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

$ curl \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
--header "Accept-API-Version: resource=1.0" \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/alice/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"
}

Update an UMA policy (REST)

To update a policy, the resource owner 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.

The ID used for a policy is always identical to the ID of the resource it protects.

$ 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":"/alpha"
}

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.

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.

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

The following example uses an SSO token to update a policy with ID 0d7790de-9066-4bb6-8e81-25b6f9d0b8853 belonging to user alice 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/realms/alpha/users/alice/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 JSON payload, 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."
}

Restrict an UMA policy (REST)

You can restrict UMA policies in the following ways:

Set an expiration date on the authorization.
Restrict the clients that can obtain an RPT.

These conditions apply to UMA policies only, and are not available to regular authorization policies.

A single UMA policy is generally represented by multiple authorization policies, with one authorization policy per permission array item.

You apply restrictions to UMA policies at the precise authorization policy for that permission; in other words, at the json/users/userId/policies endpoint, and not at the userId/uma/policies endpoint.

To obtain the UUID of the precise authorization policy, you can query the user’s authorization policies using baseUrl/json/realms/root/realms/sub_realm/users/resourceOwnerId/policies?_queryFilter=true
By default, restrictions on UMA policies do not apply to the resource owner. To change this behavior, set the Resource Owner Implicit Consent flag to false in the UMA provider configuration.

Set an expiration date

To add an expiration date to an UMA authorization, send a PUT request to the json/users/userId/policies endpoint.

This is not the uma/policies endpoint.

Add a condition object similar to the following to the policy definition:

"condition": {
    "type": "AND",
    "conditions": [
        {
            "type": "Expiration",
            "expirationDate": 1638263100
        }
    ]
}

The second type field specifies the condition type; Expiration in this case.
The expirationDate field takes a long number, in Unix epoch time format.

This example adds an expiration date to the authorization created in the previous example:

$ curl \
--request PUT \
--header 'Accept-API-Version: resource=1.0' \
--header 'content-type: application/json' \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S…Q4MTE4NTA2*" \
--header "If-Match: *" \
--data '{
  "_id": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "_rev": "1643374273953",
  "name": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "active": true,
  "description": "",
  "resources": [
    "uma://50f0d76d-b096-4998-ab55-3b7c900b01290"
  ],
  "applicationName": "uma-resource-server",
  "actionValues": {
    "view": true,
    "comment": true
  },
  "condition": {
    "type": "AND",
    "conditions": [
      {
        "type": "Expiration",
        "expirationDate": 1638263100
      }
    ]
  },
  "subject": {
    "type": "Uma",
    "claimValue": "bob"
  },
  "resourceTypeUuid": "",
  "lastModifiedBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModifiedDate": "2022-01-28T12:51:13.953Z",
  "createdBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate": "2022-01-28T10:43:31.608Z"
}' \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/alice/policies/Incredible%20Wooden%20Bacon%20-%20alice%20-%2050f0d76d-b096-4998-ab55-3b7c900b01290-97717"
{
  "_id": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "_rev": "1643728958220",
  "name": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "active": true,
  "description": "",
  "resources": [
    "uma://50f0d76d-b096-4998-ab55-3b7c900b01290"
  ],
  "applicationName": "uma-resource-server",
  "actionValues": {
    "view": true,
    "comment": true
  },
  "subject": {
    "type": "Uma",
    "claimValue": "bob"
  },
  "condition": {
    "type": "AND",
    "conditions": [
      {
        "type": "Expiration",
        "expirationDate": 1638263100
      }
    ]
  },
  "resourceTypeUuid": "",
  "lastModifiedBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModifiedDate": "2022-02-01T15:22:38.220Z",
  "createdBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate": "2022-01-28T10:43:31.608Z"
}

The request is sent to the userId/policies endpoint and the UUID of the policy is not the UMA policy’s ID, but the ID of the specific authorization policy.

Specify a client ID

To restrict the list of clients that can obtain an RPT, send a PUT request to the json/users/userId/policies endpoint.

This is not the uma/policies endpoint.

Add a condition object similar to the following to the policy definition:

"condition": {
    "type": "AND",
    "conditions": [
        {
            "type": "ClientId",
            "clientIds": [_array-of-ids_]
        }
    ]
}

The second type field specifies the condition type; ClientId in this case.
The clientIds field takes an array of client IDs.

This example restricts the clients that can request an RPT to client1 and client2:

$ curl \
--request PUT \
--header 'Accept-API-Version: resource=1.0' \
--header 'content-type: application/json' \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S…Q4MTE4NTA2*" \
--header "If-Match: *" \
--data '{
  "_id": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "_rev": "1643374273953",
  "name": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "active": true,
  "description": "",
  "resources": [
    "uma://50f0d76d-b096-4998-ab55-3b7c900b01290"
  ],
  "applicationName": "uma-resource-server",
  "actionValues": {
    "view": true,
    "comment": true
  },
  "condition": {
    "type": "AND",
    "conditions": [
      {
        "type": "ClientId",
        "clientIds": [
          "client1",
          "client2"
        ]
      }
    ]
  },
  "subject": {
    "type": "Uma",
    "claimValue": "bob"
  },
  "resourceTypeUuid": "",
  "lastModifiedBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModifiedDate": "2022-01-28T12:51:13.953Z",
  "createdBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate": "2022-01-28T10:43:31.608Z"
}' \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/alice/policies/Incredible%20Wooden%20Bacon%20-%20alice%20-%2050f0d76d-b096-4998-ab55-3b7c900b01290-97717"
{
  "_id": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "_rev": "1643798048205",
  "name": "Incredible Wooden Bacon - alice - 50f0d76d-b096-4998-ab55-3b7c900b01290-97717",
  "active": true,
  "description": "",
  "resources": [
    "uma://50f0d76d-b096-4998-ab55-3b7c900b01290"
  ],
  "applicationName": "uma-resource-server",
  "actionValues": {
    "view": true,
    "comment": true
  },
  "subject": {
    "type": "Uma",
    "claimValue": "bob"
  },
  "condition": {
    "type": "AND",
    "conditions": [
      {
        "type": "ClientId",
        "clientIds": [
          "client1",
          "client2"
        ]
      }
    ]
  },
  "resourceTypeUuid": "",
  "lastModifiedBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModifiedDate": "2022-02-02T10:34:08.205Z",
  "createdBy": "id=alice,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate": "2022-01-28T10:43:31.608Z"
}

Delete an UMA policy (REST)

To delete a policy, the resource owner 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.

The ID used for a policy is always identical to the ID of the resource it protects.

$ 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":"/alpha"
}

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.

Send 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.

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

This example uses an SSO token to delete a policy with ID 0d7790de-9066-4bb6-8e81-25b6f9d0b8853 belonging to user alice:
```
$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
--header "Accept-API-Version: resource=1.0" \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/alice/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"
}
```

When an UMA policy is deleted, all nested policies are deactivated. If that same policy is recreated, the deactivated policies are reinstated.

For example, to follow on from the example use case, Alice grants view and comment access to her medical records to Dr. Bob. Dr. Bob then creates an UMA policy, granting view and comment access to Alice’s medical records to the Surgery Center:

If Alice later deletes the policy between herself and Dr. Bob (that is, she withdraws consent for Dr. Bob to access her medical records) the policy between Dr. Bob and the Surgery Center is deactivated. The policy still exists, but the Surgery Center will not have access to Alice’s records.

If Alice later recreates the policy between herself and Dr. Bob, the policy between Dr. Bob and the Surgery Center is reactivated, and the Surgery Center will once again have access to Alice’s records:

Because the deletion of an UMA policy results in a traversal of all the nested UMA policies, deleting a policy when there is a complex graph of nested policies will have a negative performance impact.

Query UMA policies (REST)

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

$ 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":"/alpha"
}

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.

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).

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 be either resourceServer, the resource server that created the resource, or 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.

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" \
--request 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/realms/alpha/users/alice/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"
}

Log in to AM to access your profile page.
From the Shares menu, select Resources to display the list of resources you own.

Figure 1. The Resources page when logged in

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

On the Share the resource form:

Enter the username of the user with whom to share the resource.
From the Select Permission list, choose the permissions to assign to the user for the selected resource.
Click Share.

Figure 2. Sharing an UMA resource

Repeat these steps to share the resources with additional users.

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 admin UI as read-only, and cannot be edited by administrative users such as amAdmin. They can, however, be viewed and deleted.

Click Close.

PingAM 7.5.0

UMA policies

Create an UMA policy (REST)

Read an UMA policy (REST)

Update an UMA policy (REST)

Restrict an UMA policy (REST)

Set an expiration date

Specify a client ID

Delete an UMA policy (REST)

Query UMA policies (REST)

Manage UMA policies (UI)