Manage UMA user and favorite labels

The /json/users/username/oauth2/resources/labels REST endpoint lets users manage user and favorite labels. It also provides built-in user pages in the UI.

When using the REST endpoint, specify the username in the URL, and provide the SSO token of that user in the iPlanetDirectoryPro header.

Create user labels (REST)

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

To create a new user label, send a POST request with the name of the new user label and the type, USER:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=1.0' \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S…Q4MTE4NTA2*" \
--data '{
    "name" : "New Resource Label",
    "type" : "USER"
}' \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/alice/oauth2/resources/labels"
{
  "_id": "f2069e8c-bd3e-430a-b2f6-7b9f9b523e5a0",
  "_rev": "27048065",
  "name": "New Resource Label",
  "type": "USER"
}

If you set the type object as STAR, you create a favorite label.

On success, AM returns an HTTP 201 Created status code, and the unique identifier of the new user label in the _id field. Note that the label is not yet associated with a resource. To apply the new label to a resource, see Update an UMA resource (REST).

Query user labels (REST)

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

To query the labels belonging to a user, send a GET request with _queryFilter=true:

$ curl \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S…Q4MTE4NTA2*" \
--header "Accept-API-Version: resource=1.0" \
"https://openam.example.com:8443/json/realms/root/realms/alpha/users/alice/oauth2/resources/labels?_queryFilter=true"
{
    "result": [
        {
            "_id": "46a3392f-1d2f-4643-953f-d51ecdf141d44",
            "name": "2022/June/Bristol",
            "type": "USER"
        },
        {
            "_id": "60b785c2-9510-40f5-85e3-9837ac272f1b1",
            "name": "Top Level/Second Level/My Label",
            "type": "USER"
        },
        {
            "_id": "ed5fad66-c873-4b80-93bb-92656eb06deb0",
            "name": "starred",
            "type": "STAR"
        },
        {
            "_id": "db2161c0-167e-4195-a832-92b2f578c96e3",
            "name": "New Resource Set Label",
            "type": "USER"
        }
    ],
    "resultCount": 4,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}

Delete user labels (REST)

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

To delete a user label, send a DELETE request, including the ID of the label in the URL:

$ 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/oauth2/resources/labels/46a3392f-1d2f-4643-953f-d51ecdf141d44"
{
    "_id": "46a3392f-1d2f-4643-953f-d51ecdf141d44",
    "name": "2022/June/Bristol",
    "type": "USER"
}

On success, AM returns an HTTP 200 OK status code, and a JSON representation of the user label that was removed.

Label resources (UI)

Log in to the UI as a user. The profile page is displayed.
Go to Shares > Resources > My Resources, and click the name of the resource to add labels to.
On the resource details page, click Edit Labels.

In the edit box that is displayed, you can:
1. Enter the label you want to add to the resource, and click 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, this image shows the result of the label: 2015/October/Bristol:
2. Click an existing label, and then press Delete or Backspace to delete the label from the resource.
When you have finished editing labels you can:
1. Click the checkmark button to save any changes made.
2. Click the X button to cancel any changes made.

Label resources as favorites (UI)

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

Log in to AM as the resource owner user. The profile page is displayed.
Go to Shares > Resources > My Resources, and click the name of the resource to add to the list of favorites.
On the resource details page, click the star icon:

To view the list of favorite resources, click Starred.

AM 7.2.2

Manage UMA user and favorite labels

Create user labels (REST)

Query user labels (REST)

Delete user labels (REST)

Label resources (UI)

Label resources as favorites (UI)