Guide to configuring and using UMA features in ForgeRock® Access Management.

1. Log in to the AM console as an administrator.

2. In the AM console, select Realms > Realm Name > Dashboard > Configure OAuth Provider > Configure User Managed Access.

   Important

   Some IDM deployments use AM's UMA Provider Service to help support privacy use cases, such as the General Data Protection Regulation (GDPR). If you are configuring the UMA Provider Service as part of an IDM deployment, perform the following steps:

   1. In the AM console, navigate to Realms > Realm Name > Services and add an UMA Provider service.

      For information about the available attributes, see "UMA Provider".

   2. Save your changes.

3. On the Configure UMA page, select the Realm for the provider service.

4. (Optional) If necessary, adjust the lifetimes for authorization codes, access tokens, and refresh tokens.

5. (Optional) Select Issue Refresh Tokens unless you do not want the authorization service to supply a refresh token when returning an access token.

6. (Optional) Select Issue Refresh Tokens on Refreshing Access Tokens if you want the authorization service to supply a new refresh token when refreshing an access token.

7. (Optional) If you have a custom scope validator implementation, put it on the AM classpath, for example /path/to/tomcat/webapps/openam/WEB-INF/lib/, and specify the class name in the Scope Implementation Class field. For an example, see "Customizing OAuth 2.0 Scope Handling" in the OAuth 2.0 Guide.

8. Click Create to save your changes. AM creates the following:

   • An UMA provider service.

   • An OAuth2 provider service that supports OpenID Connect.

   Warning

   If an UMA or OAuth 2.0 provider service already exists, it will be overwritten with the new values.

9. To access the provider service configuration in the AM console, browse to Realms > Realm Name > Services, and then click UMA Provider.

   For information about the available attributes, see "UMA Provider".

10. To complete the configuration, click Save Changes.

Create a profile for the UMA client agent in AM for OAuth 2.0 and UMA 2.0:

1. Log in to the AM console as an administrator.

2. In the top level realm, select Applications > OAuth 2.0.

3. Click Add Client, and enter the following values:

   • Client ID: UmaClient

   • Client secret: password

   • Redirection URIs: redirection URI. For this example, leave it blank.

   • Scope(s): read openid

     Note

     You will need to enter read, press Enter, and then enter openid.

   • Default Scope(s): For this example, leave it blank.

   • Grant Types: UMA Resource Owner Password Credentials

     Note

     You will need to enter UMA, press Enter, and then enter Resource Owner Password Credentials.

Create a profile for the resource server agent in AM for OAuth 2.0 and UMA 2.0:

1. Log in to the AM console as an administrator.

2. In the top level realm, select Applications > OAuth 2.0.

3. Click Add Client, and enter the following values:

   • Client ID: Uma-Resource-Server

   • Client secret: password

   • Redirection URIs: redirection URI. For this example, leave it blank.

   • Scope(s): uma_protection

   • Default Scope(s): For this example, leave it blank.

   • Grant Types: Resource Owner Password Credentials

1. Log in to the AM console as an administrator.

2. In the top level realm, click Configure OAuth Provider > Configure OpenID Connect. Accept the defaults, and click Create.

1. Log in to the AM console as an administrator.

2. In the top level realm, click Identities.

3. Click New, and create a new requesting party. This example uses the following values:

   • ID: alice

   • First Name: Alice

   • Last Name: Resource-Owner

   • Full Name: Alice Resource-Owner

   • Password: password

   • Password (confirm): password

   • User Status: Active

4. Click OK to save the settings.

1. Log in to the AM console as an administrator.

2. In the top level realm, click Identities.

3. Click New, and create a new requesting party. This example uses the following values:

   • ID: bob

   • First Name: Bob

   • Last Name: Requesting-Party

   • Full Name: Bob Requesting-Party

   • Password: password

   • Password (confirm): password

   • User Status: Active

4. Click OK to save the settings.

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 "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service" in the OAuth 2.0 Guide.

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.

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 Protection API Token (PAT)".
  	The value returned in the _id property is the ID of the created UMA resource.

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.

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

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

   
   

When the resource server receives a request for access to a resource, it contacts the authorization server to acquire a permission ticket. The permission ticket associates a request for a particular resource with the corresponding scopes. The PAT bearer token of the resource owner is used to map the request to the correct identity.

The permission ticket and the claim token are used to obtain a requesting party access token (RPT). A new permission ticket must be used for each attempt to acquire an RPT.

• Send a POST request to the UMA permission_request endpoint:

  $ curl -X POST \
  --header 'authorization: Bearer 057ad16f-7dba-4049-9f34-e609d230d43a' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '[
      {
          "resource_id" : "ef4d750e-3831-483b-b395-c6f059b5e15d0", 
          "resource_scopes" : ["download"]
      }
  ]' \
  https://openam.example.com:8443/openam/uma/realms/root/permission_request
  {
      "ticket": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
                 LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
                 HA6Ly9vcGVuYW0uZGVmYXVsdC5leGFtcGxlLmNvbTo4MC9vcGVuYW0vb2F1dGgyIi
                 wiaXQiOjAsImV4cCI6MTUwNzE0ODI2MiwidGlkIjoiZWY0ZDc1MGUtMzgzMS00ODN
                 iLWIzOTUtYzZmMDU5YjVlMTVkMiIsImZvcmdlcm9jayI6eyJzaWciOiIzUylGOk1u
                 N0N0dVlIZVpQVVtrMGZlajJmL2JAVDBYfWI4dH1hOEQmIn19.vi6RxLMxl5MiB1uK
                 60P1yE2HIhWnF7CDFgz4agM5YAQ" 
  }

  	Use the PAT Bearer Token previously acquired on behalf of the resource owner. See "To Acquire a Protection API Token (PAT)".
  	Specify the ID of the registered resource for which this permission ticket will maintain permission state information. See "Register an UMA Resource".
  	The value returned in the ticket property is the permission ticket, which is used to obtain an RPT. See "Obtain a Requesting Party Token (RPT)".

  Note

  The default lifetime for an UMA permission ticket is 120 seconds. Attempting to obtain a requesting party token after the permission ticket has expired will fail with an error message as follows:

  {
      "error_description": "The provided access grant is invalid, expired, or revoked.", "error": "invalid_grant"
  }

  You can alter the default lifetime of a permission ticket by navigating to Realms > Realm Name > Services > UMA Provider, and editing the Permission Ticket Lifetime (seconds) property.

The authorization server must gather claims from the requesting party to create a claim token.

• Send a POST request to the OAuth 2.0 access_token endpoint. The value returned in the id_token property is the claim token required to obtain an RPT, along with the permission ticket acquired earlier:

  $ curl -X POST \
  --header 'authorization: Basic VW1hQ2xpZW50OnBhc3N3b3Jk' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=password' \
  --data 'scope=openid' \
  --data 'username=bob' \
  --data 'password=password' \
  https://openam.example.com:8443/openam/oauth2/realms/root/access_token
  {
    "access_token": "f09f55e5-5e9c-48fe-aeaa-d377de88e8e6",
    "refresh_token": "ee2d35f6-5819-4734-8b3e-9af77a545563",
    "scope": "openid",
    "id_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiJiL082T3ZWdjEreStXZ3JINVVpOVdUaW9MdDA
                 9IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoiMWpodGpUQ0JmLWdKeDFUZGR
                 EdFlIdyIsInN1YiI6ImJvYiIsImF1ZGl0VHJhY2tpbmdJZCI6IjBmZjAxNzQ0LW
                 Y5ZDMtNGFhMi04NmU4LTcyNTJlYTUyMWQ4Yi04MDIiLCJpc3MiOiJodHRwOi8vb
                 3BlbmFtLmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsInRv
                 a2VuTmFtZSI6ImlkX3Rva2VuIiwiYXVkIjoiVW1hQ2xpZW50IiwidXBkYXRlZF9
                 hdCI6IjE1MDcwODc5MDEiLCJhenAiOiJVbWFDbGllbnQiLCJhdXRoX3RpbWUiOj
                 E1MDcwODgyNjcsInJlYWxtIjoiLyIsImV4cCI6MTUwNzE0ODI2NywidG9rZW5Ue
                 XBlIjoiSldUVG9rZW4iLCJpYXQiOjE1MDcwODgyNjd9.aVEF0P0pSUsifl_aPuZ
                 QwWxhv6CvqNEbK6_kDpat_u-gfwKZZRWmdvouLa9dNmGr33EQJY4LifCUHA_AKn
                 048G3W6czBupC4TJESK4rDwKr2OXPQVzTrGNk25ix5Dw_BdngW-YJfnXmlSByKt
                 ZmaYT7FGS0bdGMedtkypVpM6uZAQcc9JEmOlOCHF-l57NH88pOP7MkY9gszlGJi
                 3cFEMHONTBB6-yroJyU-vaDJzWeCX3uGVqY8K3nUMqMguRSIkqrltabyX4CuKtN
                 JlthJUEnX4mZFBNf7un7Qs3nx3BUAzclKjL2H1FNyD2a-zx3YOJ9Wm4kj_SlgTg
                 FBznEB5A", 
    "token_type": "Bearer",
    "expires_in": 4999
  }

  	Authorize using the credentials of the UMA client. Use the client ID and client secret, separated by a colon character, for example UmaClient:password. Base64-encode the result. See "To Create an UMA Client Agent".
  	The value returned in the id_token property is the claim token, which is used to obtain an RPT. See "Obtain a Requesting Party Token (RPT)".

  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.

The requesting party makes a request using the permission ticket and the claim token, in exchange for a Requesting Party Token.

1. Send a POST request to the OAuth 2.0 access_token endpoint. Make sure to include the permission ticket, ticket, and the claim_token. The following example results in an error description, indicating that "The client is not authorised to access the requested resource set." The authorization server sends a request to the resource owner to allow or deny access to the requesting party.

   $ curl -X POST \
     --header 'authorization: Basic VW1hQ2xpZW50OnBhc3N3b3Jk' \
     --header 'cache-control: no-cache' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data 'grant_type=urn:ietf:params:oauth:grant-type:uma-ticket' \
     --data 'ticket=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
                  LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
                  HA6Ly9vcGVuYW0uZGVmYXVsdC5leG$' \
     --data 'scope=download' \
     --data 'claim_token=eyJ0eXAiOiJKV1QiLCJraWQiOiJiL082T3ZWdjEreStXZ3JINVVpOVdUaW9MdDA
                    9IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoieWExdHlyZFdBTTYwWGlfLU5
                    EUTc4ZyIsInN1YiI6ImJvYiIsImF1ZG$' \
     --data 'claim_token_format=http://openid.net/specs/openid-connect-core-1_0.html#IDToken' \
     https://openam.example.com:8443/openam/oauth2/realms/root/access_token
   {
     "ticket": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
                LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
                HA6Ly9vcGVuYW0uZGVmYXVsdC5leGFtcGxlLmNvbTo4MC9vcGVuYW0vb2F1dGgyIi
                wiaXQiOjEsImV4cCI6MTUwNzE0ODEzNSwidGlkIjoiNTkzNmExOGMtOGE2OC00YTI
                xLTliOGQtZWViNzIyOGEwMDY3MCIsImZvcmdlcm9jayI6eyJzaWciOiIqP2pMUEVV
                M3hYNm5RbU8-YXFXZ0d9aTJ1OjNnLlRrc2FKI3UpXnokIn19.a9JpfsXS09CNvr2B
                RtLDO-t4ZCnmrHr2h3auXPeJi3E",
     "error_description": "The client is not authorised to access the requested resource set. A request has been submitted to the resource owner requesting access to the resource",
     "error": "request_submitted"
   }

   	Authorize using the credentials of the UMA client. Use the username and password, separated by a colon character, for example UmaClient:password, and base64-encode the result. See "To Create an UMA Client Agent".
   	Specify the permission ticket acquired earlier. See "Create a Permission Ticket".
   	Specify the claim token acquired earlier. See "Gather Claims".

   Note

   The default lifetime for an UMA permission ticket is 120 seconds. Attempting to obtain a requesting party token after the permission ticket has expired will fail with an error message as follows:

   {
         "error_description": "The provided access grant is invalid, expired, or revoked.", "error": "invalid_grant"
         }

   If the ticket has expired, obtain another by repeating the steps in "Create a Permission Ticket".

   You can alter the default lifetime of a permission ticket by navigating to Realms > Realm Name > Services > UMA Provider, and editing the Permission Ticket Lifetime (seconds) property.

2. The resource owner, Alice, logs into AM to view the access request. She clicks Shares > Requests, and clicks Allow to grant read access to Bob, the requesting party.

   Consent Screen Presented to the Resource Owner

   
   
   

3. Because each permission token can only be used once, request a new permission token by performing the steps in "Create a Permission Ticket".

4. Resubmit the previous POST request for the RPT, with the new permission ticket obtained in the previous step and the original claim token:

   curl -X POST \
   --header 'authorization: Basic VW1hQ2xpZW50OnBhc3N3b3Jk' \
   --header 'cache-control: no-cache' \
   --header 'content-type: application/x-www-form-urlencoded' \
   --data 'grant_type=urn:ietf:params:oauth:grant-type:uma-ticket' \
   --data 'ticket=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vb3BlbmFt
           LmRlZmF1bHQuZXhhbXBsZS5jb206ODAvb3BlbmFtL29hdXRoMiIsImlzcyI6Imh0d
           HA6Ly9vcGVuYW0uZGVmYXVsdC5leG$' \
   --data 'scope=download' \
   --data 'claim_token=eyJ0eXAiOiJKV1QiLCJraWQiOiJiL082T3ZWdjEreStXZ3JINVVpOVdUaW9MdDA
           9IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoieWExdHlyZFdBTTYwWGlfLU5
           EUTc4ZyIsInN1YiI6ImJvYiIsImF1ZG$' \
   --data 'claim_token_format=http://openid.net/specs/openid-connect-core-1_0.html#IDToken' \
   https://openam.example.com:8443/openam/oauth2/realms/root/access_token
   {
       "access_token": "Aw4a92ZoKsjadWKw2d4Rmcjv7DM",
       "token_type": "Bearer",
       "expires_in": 3599
   }

   	Authorize using the same credentials of the UMA client as the first request for an RPT.
   	Specify a refreshed permission ticket acquired earlier, otherwise you will receive a response such as: The provided access grant is invalid, expired, or revoked. See "Create a Permission Ticket".
   	Specify the same claim token as the first request for an RPT.

   The access_token is the RPT, which allows the requesting party to access the resource through a client.

   You have successfully configured and tested an UMA 2.0 example demo deployment.

5. (Optional) You can use the /oauth2/introspect endpoint to inspect the properties of the RPT. Use the PAT issued to the resource owner for authenticating to the authorization server, and specify the RPT token in a query parameter named token, as follows:

   $ curl --header 'authorization: Bearer 057ad16f-7dba-4049-9f34-e609d230d43a' \
   'https://openam.example.com:8443/openam/oauth2/realms/root/introspect?token=Aw4a92ZoKsjadWKw2d4Rmcjv7DM'
   {
       "active": true,
       "permissions": [
           {
               "resource_id": "ef4d750e-3831-483b-b395-c6f059b5e15d0",
               "resource_scopes": [
                   "download"
               ],
               "exp": 1522334692
           }
       ],
       "token_type": "access_token",
       "exp": 1522334692,
       "iss": "https://openam.example.com:8443/openam/oauth2"
   }

1. Log in to AM. Your user profile page appears.

2. On the Shares menu, click Resources. A list of the resources you own appears.

   The Resources Page when Logged In

   
   
   

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

   On the Share the resource form:

   1. Enter the username of the user with whom to share the resource.

   2. From the Select Permission drop-down list, choose the permissions to assign to the user for the selected resource.

   3. Click Share.

      Sharing an UMA Resource

      
      
      

   4. Repeat these steps to share the resources with additional users.

4. When finished, click Close.

To apply labels to a resource:

1. Log in to AM as a user. The profile page is displayed.

2. Navigate to Shares > Resources > My Resources, and then click the name of the resource to add labels to.

3. On the resource details page, click Edit Labels.

   In the edit box that appears, you can:

   • Enter the label you want to add to the resource, and then press Enter.

     If you enter a label containing forward slash (/) characters, a hierarchy of each component of the label is created. The resource only appears in the last component of the hierarchy.

     For example, the screenshot below shows the result of the label: 2015/October/Bristol:

     

   • Click an existing label, and then press Delete or Backspace to delete the label from the resource.

4. When you have finished editing labels you can:

   • Click the checkmark button to save any changes made.

   • Click the X button to cancel any changes made.

Mark resources as favorites to have them appear on the Starred page.

1. Log in to AM as a user. The profile page is displayed.

2. Navigate to Shares > Resources > My Resources, and then click the name of the resource to add to the list of favorites.

3. On the resource details page, click the star icon, as shown below:

   
   
   

   To view the list of favorite resources, click Starred.

AM supports an UMA workflow in which a user can request access to a resource that has not been explicitly shared with them. The resource owner receives a notification of the request and can choose to allow or deny access.

Manage pending requests for access to resources by using the steps below:

1. Login to AM as the resource owner, and then navigate to Shares > Requests.

   The Requests page is displayed:

   UMA Requests Screen Presented to the Resource Owner

   
   
   

2. Review the pending request, and take one of the following actions:

   • Click Allow to approve the request.

     Tip

     You can remove permissions from the request by clicking the permission, and then press either Delete or Backspace. Select the permission from the drop-down list to return it to the permissions granted to the resource owner.

     The required UMA policy will be created, and optionally the requesting party will be notified that they can now access the resource.

     The requesting party can view a list of resources to which they have access by navigating to Shares > Resources > Shared with me.

   • Click Deny to prevent the requesting party from accessing the resource. The pending request is removed, and the requesting party will not be notified.

3. After allowing or denying access to a resource, an entry is created in the History page.

   To view a list of actions that have occurred, navigate to Shares > History.

To register a resource, the resource server must first acquire a PAT token on behalf of the resource owner, as described in "To Acquire a Protection API Token (PAT)".

Once you have the PAT bearer token, you can access the UMA resource_set endpoint to register resources, as shown in the following steps.

• Create a POST request to the UMA resource_set endpoint, including the PAT bearer token in an Authorization header.

  The following example uses a resource owner's PAT bearer token to register a photo album resource and a pair of system labels in a realm named subrealm:

  $ curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
  --header "Accept-API-Version: resource=1.0" \
  --data \
  '{
      "name" : "Photo Album",
      "icon_uri" : "http://photoz.example.com/icons/flower.png",
      "resource_scopes" : [
          "edit",
          "view",
          "http://photoz.example.com/dev/scopes/print"
      ],
      "labels" : [
          "3D",
          "VIP"
      ],
      "type" : "http://photoz.example.com/dev/rtypes/photoalbum"
  }' \
  https://openam.example.com:8443/openam/uma/realms/root/resource_set
  {
      "_id": "126615ba-b7fd-4660-b281-bae81aa45f7c0",
      "user_access_policy_uri": "https://openam.example.com:8443/openam/XUI/?realm=/#uma/share/126615ba-b7fd-4660-b281-bae81aa45f7c0"
  }

To list the resources registered to a user, you must first acquire a PAT token as that user, as described in "To Acquire a Protection API Token (PAT)".

Once you have the PAT token, you can access the UMA resource_set endpoint to list resources, as shown below:

• Create a GET request to the UMA resource_set endpoint, including the PAT bearer token in an Authorization header.

  The following example uses a PAT bearer token to list the registered resources in a realm named subrealm:

  $ curl \
  --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
  --header "Accept-API-Version: resource=1.0" \
  https://openam.example.com:8443/openam/uma/realms/root/resource_set
  {
      "126615ba-b7fd-4660-b281-bae81aa45f7c0",
      "3a2fe6d5-67c8-4a5a-83fb-09734f1dd5b10",
      "8ed24623-fcb5-46b8-9a64-18ee1b9b7d5d0"
  }

  On success, an array of the registered resource IDs is returned. Use the ID to identify a resource in the following procedures:

  • "To Read an UMA Resource"

  • "To Update an UMA Resource"

  • "To Delete an UMA Resource"

To read a resource, you must first acquire a PAT token on behalf of the resource owner, as described in "To Acquire a Protection API Token (PAT)".

Once you have the PAT token, you can access the UMA resource_set endpoint to read resources, as shown below:

• Create a GET request to the UMA resource_set endpoint, including the PAT bearer token in an Authorization header.

  Note

  You must provide the ID of the resource to read, specified at the end of the request, as follows: https://openam.example.com:8443/openam/uma/realms/root/resource_set/resource_set_ID.

  The following example uses a PAT bearer token and a resource ID to read a specific resource in a realm named subrealm:

  $ curl \
  --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
  https://openam.example.com:8443/openam/uma/realms/root/resource_set/126615ba-b7fd-4660-b281-bae81aa45f7c0
  {
      "resource_scopes": [
          "read",
          "view",
          "http://photoz.example.com/dev/scopes/print"
      ],
      "name": "Photo Album",
      "_id": "126615ba-b7fd-4660-b281-bae81aa45f7c0",
      "type": "https//www.example.com/rsets/photoalbum",
      "icon_uri": "http://www.example.com/icons/flower.png",
      "labels": [
          "VIP",
          "3D"
      ],
      "user_access_policy_uri":
          "https://openam.example.com:8443/openam/XUI/?realm=/#uma/share/126615ba-b7fd-4660-b281-bae81aa45f7c0"
  }

  On success, an HTTP 200 OK status code is returned, as well as a representation of the resource in the JSON body of the response.

  If the resource ID does not exist, an HTTP 404 Not Found status code is returned, as follows:

  {
   "error": "not_found",
   "error_description":
       "Resource set corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found"
  }

This example updates the UMA policy for user bob with the new scopedelete. The registered user for UMA in this example is alice who has permission to update the policy using their own SSO token in the header.

1. Before you can read or update a resource, you have to acquire a PAT token on behalf of the resource owner. See "To Acquire a Protection API Token (PAT)".

2. Add the new policy action delete to the appropriate resource type.

   $ $ curl \
   'http://openam.example.net:8080//openam/json/resourcetypes/630a0d-4d86-4b7e-848-3bf7dda7d220' \
   --request PUT \
   --header 'Accept-API-Version: protocol=1.0,resource=1.0' \
   --header 'Content-Type: application/json' \
   --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723"
   --data-raw '{"uuid":"63d10a0d-4d86-4b7e-8548-3bf70dda7d220", \
     "description":"Dynamically created resource type for the UMA resource set. \
          Used to find all Policy Engine Policies that make up an UMA Policy", \
     "actions": \
          {"download":true, \
           "view":true, \
           "comment":true, \
           "delete":true}, \
     }'

3. Send a PUT request to the UMA resource_set endpoint. Include the following:

   • A PAT bearer token in a header named Authorization

   • Any new or changed parameters in the existing values.

   • The ID of the resource to update, specified at the end of the request. Example: https://openam.example.com:8080/openam/uma/realms/root/resource_set/resource_set_ID.

   The following example uses a PAT bearer token and a resource ID to add the delete scope to a realm resource.

   $ curl \
   --request PUT \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
   --header "Accept-API-Version: resource=1.0" \
   --header "If-Match: *" \
   --data \
   '{
       "policyId": "5c322250-a39b-455e-8413-33c3f8a876e00",
       "permissions":
          [
            {
              "subject": "bob",
              "scopes": [
                 "view",
                 "comment",
                 "download",
                 "delete"
              ]
           }
          ]
   }' 
   http://openam.example.com:8080/openam/json/realms/root/users/alice/uma/policies/5c322250-a39b-455e-8413-33c3f8a876e00
   {
     "_id": "63d10a0d-4d86-4b7e-8548-3bf70dda7d220",
     "_rev": "-92235058",
     "policyId": "63d10a0d-4d86-4b7e-8548-3bf70dda7d220",
     "permissions": [
       {
         "subject": "bob",
         "scopes": [
           "download",
           "delete",
           "view",
           "comment"
         ]
       }
     ]
   }

To delete a resource, you must first acquire a PAT token, as described in "To Acquire a Protection API Token (PAT)".

Once you have the PAT token, you can access the UMA resource_set endpoint to delete resources, as shown below:

• Create a DELETE request to the UMA resource_set endpoint, including the PAT bearer token in a header named Authorization.

  Provide the ID of the resource to delete, specified at the end of the request as follows: https://openam.example.com:8443/openam/uma/realms/root/resource_set/resource_set_ID

  $ curl \
  --request DELETE \
  --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
  --header "Accept-API-Version: resource=1.0" \
  https://openam.example.com:8443/openam/uma/realms/root/resource_set/126615ba-b7fd-4660-b281-bae81aa45f7c0
    {}

  On success, an HTTP 204 No Content status code is returned, as well as an empty response body.

  If the resource ID does not exist, an HTTP 404 Not Found status code is returned as follows:

  {
      "error": "not_found",
      "error_description":
          "Resource set corresponding to id: 43225628-4c5b-4206-b7cc-5164da81decd0 not found"
  }

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.

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

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

• 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 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"
  }