PingAM 7.5.0

Resource types over REST

You can manage resource types over REST at the resourcetypes endpoint.

AM stores resource types as JSON objects. A resource type can include the following fields. The fields have JSON values—​strings, numbers, objects, sets, arrays, true, false, and null.

Resource type field Description

_id, uuid(1)

A unique, system-generated UUID string.

Use this string to identify a specific resource type. Do not change the generated UUID.

_rev(1)

A system-generated revision string.

name

A human-readable name string for the resource type.

Do not use any of the following characters in policy, policy set, or resource type names:

Double quotes (")
Plus sign (+)
Comma (,)
Less than (<)
Equals (=)
Greater than (>)
Backslash (\)
Forward slash (/)
Semicolon (;)
Null (\u0000)

description

An optional text string to help identify the resource type.

patterns

An array of resource pattern strings specifying URLs or resource names to protect.

For details, refer to Resource type patterns.

actions

An object where each field is an action name.

The value for each action name field is a boolean indicating whether to allow the action by default in policies that derive from this resource type.

createdBy(1)

A string indicating who created the resource type.

creationDate(1)

An integer containing the creation time in milliseconds since January 1, 1970.

lastModifiedBy(1)

A string indicating who last changed the resource type.

lastModifiedDate(1)

An integer containing the last modified time in milliseconds since January 1, 1970.

(1) Do not change the value of this field.

Access the endpoints

The REST calls to manage resource types rely on an account with the appropriate privileges:

  1. Create a resource type administrator.

    In the AM admin UI, select Realm > Realm Name > Identities > + Add Identity and fill the required fields.

    Record the username and password.

  2. Create a group that grants the privileges to the resource type administrator.

    Select Realms > Realm Name > Identities > Groups > + Add Group to create a group with the following settings:

    Group ID

    am-resource-type-admins

    Members

    The resource type administrator whose username you recorded

    Privileges

    Policy Admin
    Resource Type Modify Access
    Resource Type Read Access

  3. Before making REST calls to manage resource types, authenticate as the resource type administrator:

    $ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <resource-type-admin-username>' \
--header 'X-OpenAM-Password: <resource-type-admin-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<resource-type-admin-tokenId>","successUrl":"/enduser/?realm=/alpha","realm":"/alpha"}

    For additional details, refer to Session token after authentication.

    Use the <resource-type-admin-tokenId> as the value of the AM session cookie (default name: iPlanetDirectoryPro) to access the REST endpoints.

Query resource types

To list all the resource types defined for a realm, send an HTTP GET request to the /json/realms/root/realms/Realm Name/resourcetypes endpoint with _queryFilter=true as the query string parameter.

If you omit the realm path from the URL, AM uses the Top Level Realm. 
$ curl \
--header "iPlanetDirectoryPro: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/resourcetypes?_queryFilter=true'
[{
  "result": [{
    "_id": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
    "uuid": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
    "name": "Light",
    "description": "",
    "patterns": ["light://*/*"],
    "actions": {
      "switch_off": false,
      "switch_on": false
    },
    "createdBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
    "creationDate": 1669038769034,
    "lastModifiedBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
    "lastModifiedDate": 1669038769034
  }, {
    "_id": "76656a38-5f8e-401b-83aa-4ccb74ce88d2",
    "uuid": "76656a38-5f8e-401b-83aa-4ccb74ce88d2",
    "name": "URL…​"
  }, {
    "_id": "d60b7a71-1dc6-44a5-8e48-e4b9d92dee8b",
    "uuid": "d60b7a71-1dc6-44a5-8e48-e4b9d92dee8b",
    "name": "OAuth2 Scope…​"
  }],
  "resultCount": 3,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": 0
}

Adapt the query string parameters to refine the results.

Field Supported _queryFilter operators

uuid

Equals (eq)
Contains (co)
Starts with (sw)

name

description

patterns

actions

Read a resource type

To read a resource type in a realm, send an HTTP GET request to the /json/realms/root/realms/Realm Name/resourcetypes/uuid endpoint, where uuid is the value of the "uuid" field for the resource.

If you omit the realm path from the URL, AM uses the Top Level Realm. 
$ curl \
--header "iPlanetDirectoryPro: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/resourcetypes/fcaee7dc-f99c-43b1-b10d-592e1c4bd394'
{
  "_id": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
  "_rev": "1669045336245",
  "uuid": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
  "name": "Light",
  "description": "",
  "patterns": ["light://*/*"],
  "actions": {
    "switch_off": false,
    "switch_on": false
  },
  "createdBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
  "creationDate": 1669038769034,
  "lastModifiedBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
  "lastModifiedDate": 1669038769034
}

Create a resource type

To create a resource type in a realm, send an HTTP POST request to the /json/realms/root/realms/Realm Name/resourcetypes endpoint with _action=create as the query string parameter and a JSON representation of the resource type as the POST data.

If you omit the realm path from the URL, AM uses the Top Level Realm.

AM generates the UUID for the resource.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "My Resource Type",
  "actions": {
    "LEFT": true,
    "RIGHT": true,
    "UP": true,
    "DOWN": true
  },
  "patterns": ["https://device/location/*"]
}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/resourcetypes/?_action=create'
{
  "_id": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "uuid": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "name": "My Resource Type",
  "description": null,
  "patterns": ["https://device/location/*"],
  "actions": {
    "RIGHT": true,
    "DOWN": true,
    "UP": true,
    "LEFT": true
  },
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": 1669045619375,
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "lastModifiedDate": 1669045619375
}

Update a resource type

To update a resource type in a realm, send an HTTP PUT request to the /json/realms/root/realms/Realm Name/resourcetypes/uuid endpoint, where uuid is the value of the "uuid" field for the resource. Include a JSON representation of the resource type as the PUT body, making sure the "uuid" and "_id" fields match the original resource.

If you omit the realm path from the URL, AM uses the Top Level Realm. 
$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "My Resource Type",
  "actions": {
    "LEFT": true,
    "RIGHT": true,
    "UP": false,
    "DOWN": false
  },
  "patterns": ["https://device/location/*"]
}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/resourcetypes/c7e09ca1-a0db-4434-9327-ca685ae99899'
{
  "_id": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "uuid": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "name": "My Resource Type",
  "description": null,
  "patterns": ["https://device/location/*"],
  "actions": {
    "RIGHT": true,
    "DOWN": false,
    "UP": false,
    "LEFT": true
  },
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": 1669045619375,
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "lastModifiedDate": 1669045765822
}

Delete a resource type

To delete a resource type from a realm, send an HTTP DELETE request to the /json/realms/root/realms/Realm Name/resourcetypes/uuid endpoint, where uuid is the value of the "uuid" field for the resource.

If you omit the realm path from the URL, AM uses the Top Level Realm. 
$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/resourcetypes/c7e09ca1-a0db-4434-9327-ca685ae99899'
{"_id":"c7e09ca1-a0db-4434-9327-ca685ae99899","_rev":"0"}

AM does not permit deletion of a resource type when a policy set or policy depends on it. If you attempt to delete a resource type that is in use, AM returns an HTTP 409 Conflict status code and a message like the one in the following example:

$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/resourcetypes/76656a38-5f8e-401b-83aa-4ccb74ce88d2'
{
  "code": 409,
  "reason": "Conflict",
  "message": "Unable to remove resource type 76656a38-5f8e-401b-83aa-4ccb74ce88d2 because it is referenced in the policy model."
}

Remove the dependency on the resource type from all policy sets and policies before you delete it.