Resource types over REST
You can manage resource types over REST at the resourcetypes
endpoint.
Resource types are realm-specific. The URI for the resource types API can therefore contain a realm component,
for example, json/realms/root/realms/myRealm/resourcetypes
.
Resource types take the form of standard JSON objects and values (strings, numbers, objects, sets, arrays, true
, false
,
and null
). Each resource type has a unique, system-generated UUID, which must be used when modifying existing resource
types. Renaming a resource type does not affect the UUID.
Example
{
"uuid": "12345a67-8f0b-123c-45de-6fab78cd01e2",
"name": "URL",
"description": "The built-in URL Resource Type available to OpenAM Policies.",
"patterns": [
"*://*:*/*?*",
"*://*:*/*"
],
"actions": {
"POST": true,
"PATCH": true,
"GET": true,
"DELETE": true,
"OPTIONS": true,
"HEAD": true,
"PUT": true
},
"createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate": 1422892465848,
"lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate": 1422892465848
}
A resource type object can include the following fields:
uuid
-
String matching the unique identifier AM generated for the resource type when created.
name
-
The name provided for the resource type.
description
-
An optional text string to help identify the resource type.
patterns
-
An array of resource patterns specifying individual URLs or resource names to protect.
For more information on patterns in resource types and policies, see Specifying Resource Patterns with Wildcards.
actions
-
Set of string action names, each set to a boolean indicating whether the action is allowed.
createdBy
-
A string containing the universal identifier DN of the subject that created the resource type.
creationDate
-
An integer containing the creation date and time, in ISO 8601 format.
lastModifiedBy
-
A string containing the universal identifier DN of the subject that most recently updated the resource type.
If the resource type has not been modified since it was created, this will be the same value as
createdBy
. lastModifiedDate
-
An string containing the last modified date and time, in ISO 8601 format.
If the resource type has not been modified since it was created, this will be the same value as
creationDate
.
Before making a REST API call to manage a resource type, make sure that you have:
-
Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.
-
Obtained the session token returned after successful authentication.
When making a REST API call, specify the realm in the path component of the endpoint.
You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.
Query resource types
To list all the resource types in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/resourcetypes
endpoint,
with _queryFilter=true
.
The <session-cookie-name>
header is required and should contain the SSO token of an administrative user,
such as amAdmin
, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/myrealm/resourcetypes?_queryFilter=true'
{
"result":[
{
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
"name":"LIGHTS",
"description":"",
"patterns":[
"light:///"
],
"actions":{
"switch_off":true,
"switch_on":true
},
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":1431013059131,
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":1431013069803
}
],
"resultCount":1,
"pagedResultsCookie":null,
"remainingPagedResults":0
}
Additional query strings can be specified to alter the returned results. For more information, see Query.
Supported _queryFilter Fields and Operators
Field | Supported Operators |
---|---|
|
Equals ( |
|
Equals ( |
|
Equals ( |
|
Equals ( |
|
Equals ( |
Read a resource type
To read a specific resource types in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/resourcetypes
endpoint, specifying the UUID in the URL.
The <session-cookie-name>
header is required and should contain the SSO token of an administrative user,
such as amAdmin
, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e3'
{
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
"name":"LIGHTS",
"description":"",
"patterns":[
"light:///"
],
"actions":{
"switch_off":true,
"switch_on":true
},
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":1431013059131,
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":1431013069803
}
Create a resource type
To create a resource type in a realm, send an HTTP POST request to the /json/realms/root/realms/realm/resourcetypes
endpoint, with
_action=create
. Include a JSON representation of the resource type in the POST data.
The <session-cookie-name>
header is required and should contain the SSO token of an administrative user,
such as amAdmin
, who has access to perform the operation.
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"
). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("
), plus sign (+
), comma (,
), less than (<
), equals (=
), greater than (>
),
backslash (\
), forward slash (/
), semicolon (;
), and null (\u0000
).
$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "<session-cookie-name>: AQIC5…" \ --header "Accept-API-Version: resource=1.0" \ --data '{ "name":"My Resource Type", "actions":{ "LEFT":true, "RIGHT":true, "UP":true, "DOWN":true }, "patterns":[ "http://device/location/" ] }' \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/myrealm/resourcetypes/?_action=create' { "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4", "name":"My Resource Type", "description":null, "patterns":[ "http://device/location/" ], "actions":{ "RIGHT":true, "DOWN":true, "UP":true, "LEFT":true }, "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "creationDate":1431099940616, "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "lastModifiedDate":1431099940616 }
Update a resource type
To update a specific resource type in a realm, send an HTTP PUT request to the /json/realms/root/realms/realm/resourcetypes
endpoint, specifying the UUID in both the URL and the PUT body. Include a JSON representation of the updated resource type in the PUT data, alongside the UUID.
The <session-cookie-name>
header is required and should contain the SSO token of an administrative user,
such as amAdmin
, who has access to perform the operation.
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"
). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("
), plus sign (+
), comma (,
), less than (<
), equals (=
), greater than (>
),
backslash (\
), forward slash (/
), semicolon (;
), and null (\u0000
).
$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
--data '{
"name":"My Resource Type",
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4"
"actions":{
"LEFT":true,
"RIGHT":true,
"UP":false,
"DOWN":false
},
"patterns":[
"http://device/location/"
]
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4'
{
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
"name":"My Resource Type",
"description":null,
"patterns":[
"http://device/location/"
],
"actions":{
"RIGHT":true,
"DOWN":true,
"UP":false,
"LEFT":false
},
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":1431099940616,
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":1637667798885
}
Delete a resource type
To delete a specific resource types in a realm, send an HTTP DELETE request to the /json/realms/root/realms/realm/resourcetypes
endpoint, specifying the UUID in the URL.
The <session-cookie-name>
header is required and should contain the SSO token of an administrative user,
such as amAdmin
, who has access to perform the operation.
$ curl \
--request DELETE \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4'
{}
You can only delete resource types that are not being used by a policy set or policy. If you attempt to delete a resource type that is in use, AM returns an HTTP 409 Conflict status code, with a message such as:
{ "code": 409, "reason": "Conflict", "message": "Unable to remove resource type 12345a67-8f0b-123c-45de-6fab78cd01e4 because it is referenced in the policy model." }
Remove the resource type from any associated policy sets or policies before you delete it.