Registering and Protecting Resources

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

UMA 2.0 Protecting a Resource Flow
  • 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", (1)
        "refresh_token": "340f82a4-9aa9-471c-ac42-f0ca1809c82b",
        "scope": "uma_protection",
        "token_type": "Bearer",
        "expires_in": 4999
    }

    1

    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' \(1)
    --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", (2)
        "user_access_policy_uri": "https://openam.example.com:8443/openam/XUI/?realm=/#uma/share/0d7790de-9066-4bb6-8e81-25b6f9d0b8853"
    }

    1

    Use the PAT Bearer Token previously acquired on behalf of the resource owner. See "To Acquire a PAT".

    2

    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 and have an SSO token issued to them, and must also have the resource ID to be protected. This information is used when creating policies.

For more information on authenticating to AM to obtain an SSO token for a user, see "Logging in to AM Using REST".

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.

  • 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 the value of policyId in the body, and also in the URI.

    Note

    The SSO token must have been issued to the resource owner. In this example, the resource owner is alice. The following is an example of how to obtain the SSO token for a user:

    $ 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",         (1)
        "realm":"/"
    }

    1

    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.

    The following 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*" \(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/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".

    3

    Note that the returned _id value of the new policy set is identical to the ID of the registered resource.

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

    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'."
    }
Read a different version of :