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

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

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

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

5. (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.

6. (Optional) If you have a custom scope validator implementation, put it on the OpenAM 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.

7. Click Create to save your changes. OpenAM creates the following:

   • An UMA provider service.

   • An OAuth2 provider service that supports OpenID Connect.

   • A policy to protect the OAuth2 authorization endpoints.

   Warning

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

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

   To complete the configuration, click Save Changes.

Resource Sets Store properties are inherited from the defaults. For more information about inherited properties, see "Configuring Servers" in the Reference

1. Log in to the AM console as an OpenAM administrator, for example amadmin.

2. Navigate to Deployment > Servers > Server Name > UMA > Resource Sets Store.

   • Unlock the Store Mode property and choose External Token Store.

   • Unlock the Root Suffix property and enter the base DN of the store. For example dc=uma-rs,dc=example,dc=com.

   • Save your work.

3. Navigate to Deployment > Servers > Server Name > UMA > External Resource Sets Store Configuration.

   • Enter the properties for the store. For information about the available settings, see "UMA Properties".

   • Save your work.

UMA Audit Store properties are inherited from the defaults. For more information about inherited properties, see "Configuring Servers" in the Reference

1. Log in to the AM console as an OpenAM administrator, for example amadmin.

2. Navigate to Deployment > Servers > Server Name > UMA > UMA Audit Store.

   • Unlock the Store Mode property and choose External Token Store.

   • Unlock the Root Suffix property and enter the base DN of the store. For example dc=uma-rs,dc=example,dc=com.

   • Save your work.

3. Navigate to Deployment > Servers > Server Name > UMA > External UMA Audit Store Configuration.

   • Enter the properties for the store. For information about the available settings, see "UMA Properties".

   • Save your work.

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 set ID to be protected. This information is used when creating policies.

• Create a PUT request to the policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource set ID as the value of policyId in the body.

  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 create a policy to share a resource set belonging to user demo with two subjects, with different scopes for each:

  $ curl \
   --request PUT \
   --header "Content-Type: application/json" \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --data \
   '{
     "policyId": "43225628-4c5b-4206-b7cc-5164da81decd0",
     "permissions":
    [
     {
      "subject": "user.1",
       "scopes": ["http://photoz.example.com/dev/scopes/view"]
     },
     {
       "subject": "user.2",
        "scopes": [
           "http://photoz.example.com/dev/scopes/view",
           "http://photoz.example.com/dev/scopes/all"
        ]
     }
    ]
   }' \
  https://openam.example.com:8443/openam/json/realms/root/users/demo/uma/policies?_action=create
  {}

  On success, an HTTP 201 Created status code is returned, with an empty JSON body as the response.

  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'."
  }

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 policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource set 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*" \
   https://openam.example.com:8443/openam/json/realms/root/users/demo\
   /uma/policies/43225628-4c5b-4206-b7cc-5164da81decd0
  {
   "policyId": "43225628-4c5b-4206-b7cc-5164da81decd0",
   "name": "Photo Album",
   "permissions": [
      {
        "subject": "user.1",
        "scopes": [
           "http://photoz.example.com/dev/scopes/view"
        ]
      },
      {
        "subject": "user.2",
        "scopes": [
           "http://photoz.example.com/dev/scopes/view",
           "http://photoz.example.com/dev/scopes/all"
        ]
      }
   ]
  }

  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 policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource set 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 43225628-4c5b-4206-b7cc-5164da81decd0 belonging to user demo with a new scope for one of the subjects:

  $ curl \
   --request PUT \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --data \
   '{
     "policyId": "43225628-4c5b-4206-b7cc-5164da81decd0",
     "permissions":
     [
       {
          "subject": "user.1",
          "scopes": [
             "http://photoz.example.com/dev/scopes/view",
             "http://photoz.example.com/dev/scopes/all"
          ]
       },
       {
          "subject": "user.2",
          "scopes": [
            "http://photoz.example.com/dev/scopes/view",
          "  http://photoz.example.com/dev/scopes/all"
          ]
       }
     ]
   }' \
   https://openam.example.com:8443/openam/json/realms/root/users/demo\
  /uma/policies/43225628-4c5b-4206-b7cc-5164da81decd0
  {}

  On success, an HTTP 204 Empty 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"
  }

  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 policies endpoint, including the SSO token in a header based on the configured session cookie name (default: iPlanetDirectoryPro), and the resource set 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 43225628-4c5b-4206-b7cc-5164da81decd0 belonging to user demo:

  $ curl \
   --request DELETE \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   https://openam.example.com:8443/openam/json/realms/root/realms/root/users/demo\
   /uma/policies/43225628-4c5b-4206-b7cc-5164da81decd0
  {}

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

  • 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 "user.1"

  When URL-encoded becomes:

  resourceServer+eq+%22UMA-Resource-Server%22+AND+permissions%2Fsubject+eq+%22user.1%22

  The following example uses an SSO token to query the policies belonging to user demo, which have a subject user.1 in the permissions:

  $ curl \
   --header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
   --get \
   --data-urlencode '_sortKeys=policyId,name' \
   --data-urlencode '_pageSize=1' \
   --data-urlencode '_pagedResultsOffset=0' \
   --data-urlencode \
   '_queryFilter=permissions/subject eq "user.1"' \
   https://openam.example.com:8443/openam/json/realms/root/users/demo/uma/policies
  {
   "result": [
     {
        "policyId": "52645907-e20b-4351-8e0c-523ebe0d44710",
        "name": "Photo Album",
        "permissions": [
           {
               "subject": "user.1",
               "scopes": [
                   "http://photoz.example.com/dev/scopes/view"
               ]
           },
           {
                "subject": "user.2",
                "scopes": [
                  "http://photoz.example.com/dev/scopes/all",
                  "http://photoz.example.com/dev/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"
  }

OpenAM provides the /uma/permission_request REST endpoint for a resource server to register an access request on behalf of a client.

To register a permission request, the resource server must first acquire a PAT token, as described in "To Acquire a Protection API Token".

Once you have the PAT bearer token, you can access the /uma/permission_request endpoint to register a permission request, as shown below:

• Create a POST request to the permission_request endpoint, including the PAT bearer token in a header named Authorization:

  $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer 515d6551-6512-5279-98b6-c0ef3f03a723" \
   --data \
   '{
     "resource_set_id" : "43225628-4c5b-4206-b7cc-5164da81decd0",
     "scopes" : [
       "http://photoz.example.com/dev/scopes/view",
       "http://photoz.example.com/dev/scopes/all"
     ]
   }' \
   https://openam.example.com:8443/openam/uma/permission_request
  {
   "ticket": "dc630c21-7d55-45bf-958d-24d624441138"
  }

  On success, an HTTP 201 Created status code is returned, as well as a ticket property in the JSON-formatted body, which can be used by the client to acquire a requesting party token. For more information, see "To Acquire a Requesting Party Token".

  If the resource set does not allow the requested scopes, an error is returned, as follows:

  {
   "error_description": "Requested scopes are not in allowed scopes for resource set.",
   "error": "invalid_scope"
  }

You must have first registered an OAuth 2.0 client with a name, such as UMA-Client and a client password, such as password. Ensure that uma_authorization is in the list of available scopes in the client, and a redirection URI is configured. See "Registering OAuth 2.0 Clients With the Authorization Service" in the OAuth 2.0 Guide.

After a suitable OAuth 2.0 client is configured, perform the following steps to acquire an AAT:

1. Direct the requesting party to the authorization server to obtain an AAT. The URL should specify the client name registered above, the redirect URI, and request the uma_authorization scope, as shown in the example below:

   https://openam.example.com:8443/openam/oauth2/realms/root/authorize?client_id=UMA-Client&redirect_uri=http://openam.example.com:8080&response_type=code&scope=uma_authorization

   This example uses the OAuth 2.0 code grant, however the UMA client can use any of the OAuth 2.0 grants to obtain the access token.

2. After logging in, the consent screen asks the requesting party to allow or deny the requested scopes.

   Consent Screen Presented to the Requesting Party

   
   
   

3. If the requesting party allows access, they are sent to the configured redirection URL, which will have a code query string parameter added, which is used to request the AAT.

4. Create a POST request to the /oauth2/access_token endpoint, with the client credentials registered earlier, a grant type of authorization_code, a redirect URL, and the value of the code query string parameter returned in the previous step, as shown below:

   $ curl \
    --request POST \
    --data 'client_id=UMA-Client' \
    --data 'client_secret=password' \
    --data 'grant_type=authorization_code' \
    --data 'code=2b911969-5b8e-4d07-bf34-612917a37c9d' \
    --data 'redirect_uri=http%3A%2F%2Fopenam.example.com%3A8080' \
    http://openam.example.com:8080/openam/oauth2/realms/root/access_token
   
   {
    "scope": "uma_authorization print",
    "expires_in": 599,
    "token_type": "Bearer",
    "refresh_token": "e77fac0e-0dc6-40c3-a600-3309451bd6ee",
    "access_token": "d47c2278-460b-41e8-bf98-a8a1206e2c58"
   }

   The value returned in access_token is the AAT bearer token, used in the following procedures.

OpenAM provides the /uma/authz_request REST endpoint for acquiring a Requesting Party Token (RPT).

The endpoint is protected - access requires a Authorization API Token (AAT) - an OAuth 2.0 token with a scope of uma_authorization. A client must acquire an AAT in order to use the authorization request endpoint. For more information, see "To Acquire an Authorization API Token".

Once the client has an AAT bearer token, it can access the /uma/authz_request endpoint to acquire an RPT, as shown below:

• Create a POST request to the authz_request endpoint, including the AAT bearer token in a header named Authorization, and the permission token in the JSON body of the request, as follows:

  $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer 3b08e99c-b09d-4a65-9780-ea0c9e1f0f52" \
   --data \
   '{
     "ticket": "dc630c21-7d55-45bf-958d-24d624441138"
   }' \
   https://openam.example.com:8443/openam/uma/authz_request
  {
   "rpt": "162d6137-68a4-4e8e-950d-edd834589eb73"
  }

  On success, an HTTP 201 Created status code is returned, as well as the rpt property in the JSON-formatted body.

  If the resource owner has not shared the resource with the requesting party, an HTTP 403 Forbidden is returned. If OpenAM is configured to email the resource owner upon pending request creation as described in "UMA Provider", the JSON body returned includes a message that the resource owner will be notified to allow or deny access to the resource, as shown below:

  {
   "error": "request_submitted",
   "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"
  }

  For more information, see "To View and Manage Pending Access Requests"

1. Log in to OpenAM. 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. In 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 OpenAM 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 OpenAM 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.

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