How to Manage UMA User and Favorite Labels

AM provides the /json/users/username/oauth2/resources/labels REST endpoint to let users manage user 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.

To Create User Labels (REST)

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: 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":"/"
}

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, create a POST request with the name of the new user label and the type, USER, as shown below:

$ 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/users/demo/oauth2/resources/labels
{
    "_id": "db2161c0-167e-4195-a832-92b2f578c96e3",
    "_rev": "-785293115",
    "name": "New Resource Set Label",
    "type": "USER"
}

Tip

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

On success, AM returns an HTTP 201 Created status code as well as the unique identifier of the new user label in the _id property in the JSON-formatted body. Note that the user label is not yet associated with a resource. To apply the new label to a resource, see "To Update an UMA Resource (REST)".

To Query User Labels (REST)

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: 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":"/"
}

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, create a GET request including _queryFilter=true in the query string, as shown below:

$ curl \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/json/realms/root/users/demo/oauth2/resources/labels?_queryFilter=true
{
    "result": [
        {
            "_id": "46a3392f-1d2f-4643-953f-d51ecdf141d44",
            "name": "2015/October/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
}

To Delete User Labels (REST)

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: 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":"/"
}

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 belonging to a user, create a DELETE request including the ID of the user label to delete in the URL, as shown below:

$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5wM2LY4S...Q4MTE4NTA2*" \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/json/realms/root/users/demo/oauth2/resources/labels/46a3392f-1d2f-4643-953f-d51ecdf141d44
{
    "_id": "46a3392f-1d2f-4643-953f-d51ecdf141d44",
    "name": "2015/October/Bristol",
    "type": "USER"
}

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

To Label Resources Using (UI)

To apply labels to a resource using the UI:

Log in to AM as a user. The profile page is displayed.
Go to Shares > Resources > My Resources, and then click the name of the resource to add labels to.
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.
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.

To Label Resources as Favorites with the 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 then click the name of the resource to add to the list of favorites.
On the resource details page, click the star icon, as shown below:

To view the list of favorite resources, click Starred.