Registering and Protecting Resources

The resource owner must acquire a protection API access token (PAT) to register a resource and create UMA policies.

A resource owner wants to make a resource sharable and sends a request to the resource server (labeled 1 in the diagram).
The resource server requires the resource owner to acquire an protection API access token (PAT) on the authorization server (2).
The authorization server returns a PAT, which lets the resource owner register resources and manage policies (3).
The resource server registers the resource on the authorization server at the resource registration endpoint (4).
The resource owner creates a policy after registering the resource (5).

Resource registration can occur at three different stages: at initial resource creation, when needed for policy creation, and at resource access attempt. The resource registration process is the same regardless of when it is run.

To register a resource and create UMA policies, perform the following procedures:

To Acquire a PAT

First, register an OAuth 2.0 client with a name, such as UMA-Resource-Server and a client password, such as password. Ensure that uma_protection is in the list of available scopes in the client, and a redirection URI is configured. See Client Registration.

This example uses the OAuth 2.0 Resource Owner Password Credentials grant type; however, the UMA resource server can use any of the OAuth 2.0 grants, except the client credentials grant, to obtain the access token.

After a suitable OAuth 2.0 client is configured, perform the following steps to acquire a PAT on behalf of the resource owner, alice:

Create a POST request to the OAuth 2.0 access_token endpoint. The following example uses the Resource Owner Password Credentials grant type:
```
$ curl \
--request POST \
--data 'grant_type=password' \
--data 'scope=uma_protection' \
--data 'username=alice' \
--data 'password=password' \
--data 'client_id=UMA-Resource-Server' \
--data 'client_secret=password' \
https://openam.example.com:8443/openam/oauth2/realms/root/access_token
     {
    "access_token": "057ad16f-7dba-4049-9f34-e609d230d43a", 
    "refresh_token": "340f82a4-9aa9-471c-ac42-f0ca1809c82b",
    "scope": "uma_protection",
    "token_type": "Bearer",
    "expires_in": 4999
}
```
The value returned in access_token is the Protection API Token, or PAT Bearer token.
Note
To use the Resource Owner Password Credentials grant type, as described in RFC 6749, the default authentication chain in the relevant realm must allow authentication using only a username and password, for example by using a DataStore module. Attempting to use the Resource Owner Password Credentials grant type with a chain that requires any additional input returns an HTTP 500 Server Error message.

Register an UMA Resource

After acquiring a PAT, the resource owner can now register a resource on the authorization server.

Send a POST request to the UMA resource_set endpoint to register the resource, my resource 106. Make sure to use the resource_scopes attribute to define your scopes and the PAT as your resource owner's bearer token:

$ curl -X POST \
--header 'authorization: Bearer 057ad16f-7dba-4049-9f34-e609d230d43a' \
--header 'cache-control: no-cache' \
--header 'content-type: application/json' \
--data '{
    "resource_scopes": [
        "view", "comment", "download"
    ],
    "name": "my resource 106",
    "type": "type"
}' \
https://openam.example.com:8443/openam/uma/realms/root/resource_set
     {
    "_id": "0d7790de-9066-4bb6-8e81-25b6f9d0b8853", 
    "user_access_policy_uri": "https://openam.example.com:8443/openam/XUI/?realm=/#uma/share/0d7790de-9066-4bb6-8e81-25b6f9d0b8853"
}

	Use the PAT Bearer Token previously acquired on behalf of the resource owner. See "To Acquire a PAT".
	The value returned in the `_id` property is the ID of the created UMA resource.

To Create an UMA Policy

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: password" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/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.

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 -X 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".
	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