PingOne Advanced Identity Cloud

System objects

System objects, which are objects that are stored in remote systems, are exposed under the /openidm/system context. IDM provides access to system objects over REST.

The following list describes the URIs and specifies the HTTP operations to use:

/openidm/system?_action=action-name

HTTP POST

  • _action=availableConnectors returns a list of the connectors that are available in openidm/connectors or in openidm/bundle.

  • _action=createCoreConfig takes the supplied connector reference (connectorRef) and adds the configuration properties required for that connector. This generates a core connector configuration that you can use to create a full configuration with the createFullConfig action.

  • _action=createFullConfig generates a complete connector configuration, using the configuration properties from the createCoreConfig action and retrieving the object types and operation options from the resource, to complete the configuration.

  • _action=test returns a list of all remote systems, with their status and supported object types.

  • _action=testConfig validates the connector configuration provided in the POST body.

  • _action=liveSync triggers a liveSync operation on the specified source object.

  • _action=authenticate authenticates to the specified system with the credentials provided.

/openidm/system/system-name?_action=action-name

HTTP POST

  • _action=test tests the status of the specified system.

/openidm/system/system-name/system-object?_action=action-name

HTTP POST

  • _action=liveSync triggers a liveSync operation on the specified system object.

  • _action=script runs the specified script on the system object.

  • _action=authenticate authenticates to the specified system object, with the provided credentials.

  • _action=create creates a new system object.

/openidm/system/system-name/system-object?_queryId=query-all-ids

HTTP GET

Lists all IDs related to the specified system object, such as users and groups.

/openidm/system/system-name/system-object?_queryFilter=filter

HTTP GET

Lists the item(s) associated with the query filter.

/openidm/system/system-name/system-object/id

HTTP PUT

Creates a system object, or updates the system object, if it exists (replaces the entire object).

/openidm/system/system-name/system-object/id

HTTP PATCH

Updates the specified fields of a system object.

/openidm/system/system-name/system-object/id

HTTP DELETE

Deletes a system object.

When you create a system object with a PUT request (that is, specifying a client-assigned ID), you should specify the ID in the URL only and not in the JSON payload. If you specify a different ID in the URL and in the JSON payload, the request will fail, with an error similar to the following:

{
    "code":500,
    "reason":"Internal Server Error",
    "message":"The uid attribute is not single value attribute."
}

A POST request with a patch action is not currently supported on system objects. To patch a system object, you must send a PATCH request.

List available connector configurations:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"https://<tenant-env-fqdn>/openidm/system?_action=availableConnectors"
{
    "connectorRef": [
        {
            "displayName": "Workday Connector",
            "bundleVersion": "1.5.20.12",
            "systemType": "provisioner.openicf",
            "bundleName": "org.forgerock.openicf.connectors.workday-connector",
            "connectorName": "org.forgerock.openicf.connectors.workday.WorkdayConnector"
        },
        {
            "displayName": "SuccessFactors Connector",
            "bundleVersion": "1.5.20.12",
            "systemType": "provisioner.openicf",
            "bundleName": "org.forgerock.openicf.connectors.successfactors-connector",
            "connectorName": "org.forgerock.openicf.connectors.successfactors.SuccessFactorsConnector"
        },
        {
            "displayName": "ServiceNow Connector",
            "bundleVersion": "1.5.20.12",
            "systemType": "provisioner.openicf",
            "bundleName": "org.forgerock.openicf.connectors.servicenow-connector",
            "connectorName": "org.forgerock.openicf.connectors.servicenow.ServiceNowConnector"
        },
        ...
    ]
}

List remote systems, and their status:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"https://<tenant-env-fqdn>/openidm/system?_action=test"
[
  {
    "name": "ldap",
    "enabled": true,
    "config": "config/provisioner.openicf/ldap",
    "connectorRef": {
      "bundleVersion": "[1.4.0.0,1.6.0.0)",
      "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
      "connectorName": "org.identityconnectors.ldap.LdapConnector"
    },
    "displayName": "LDAP Connector",
    "objectTypes": [
      "ALL",
      "account",
      "group"
    ],
    "ok": true
  }
]

Run liveSync on a specified system object:

  • Source Parameter

  • Endpoint

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"https://<tenant-env-fqdn>/openidm/system?_action=liveSync&source=system/ldap/account"
{
  "connectorData": {
    "nativeType": "integer",
    "syncToken": 0
  },
  "_rev": "00000000a92657c7",
  "_id": "SYSTEMLDAPACCOUNT"
}
curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"https://<tenant-env-fqdn>/openidm/system/ldap/account?_action=liveSync"
{
  "connectorData": {
    "nativeType": "integer",
    "syncToken": 0
  },
  "_rev": "00000000a92657c7",
  "_id": "SYSTEMLDAPACCOUNT"
}

Run a script on a system object:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"https://<tenant-env-fqdn>/openidm/system/ldap/account?_action=script&_scriptId=addUser"

Authenticate to a system object

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "username" : "bjensen",
  "password" : "Passw0rd"
}' \
"https://<tenant-env-fqdn>/openidm/system/ldap/account?_action=authenticate"
{
  "_id": "fc252fd9-b982-3ed6-b42a-c76d2546312c"
}

Create a new system object

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "cn": "James Smith",
  "dn": "uid=jsmith,ou=people,dc=example,dc=com",
  "uid": "jsmith",
  "sn": "Smith",
  "givenName":"James",
  "mail": "jsmith@example.com",
  "description": "Created by IDM REST"}' \
--request POST \
"https://<tenant-env-fqdn>/openidm/system/ldap/account?_action=create"
{
  "telephoneNumber": null,
  "description": "Created by IDM REST",
  "mail": "jsmith@example.com",
  "givenName": "James",
  "cn": "James Smith",
  "dn": "uid=jsmith,ou=people,dc=example,dc=com",
  "uid": "jsmith",
  "ldapGroups": [],
  "sn": "Smith",
  "_id": "07b46858-56eb-457c-b935-cfe6ddf769c7"
}

Rename a system object

You can rename a system object simply by supplying a new naming attribute value in a PUT request. The PUT request replaces the entire object. The naming attribute depends on the external resource.

The following example renames an object on an LDAP server, by changing the DN of the LDAP object (effectively performing a modDN operation on that object). The example renames the user created in the previous example:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match: *" \
--data '{
  "cn": "James Smith",
  "dn": "uid=jimmysmith,ou=people,dc=example,dc=com",
  "uid": "jimmysmith",
  "sn": "Smith",
  "givenName": "James",
  "mail": "jsmith@example.com"}' \
--request PUT \
"https://<tenant-env-fqdn>/openidm/system/ldap/account/07b46858-56eb-457c-b935-cfe6ddf769c7"
{
  "mail": "jsmith@example.com",
  "cn": "James Smith",
  "sn": "Smith",
  "dn": "uid=jimmysmith,ou=people,dc=example,dc=com",
  "ldapGroups": [],
  "telephoneNumber": null,
  "description": "Created by IDM REST",
  "givenName": "James",
  "uid": "jimmysmith",
  "_id": "07b46858-56eb-457c-b935-cfe6ddf769c7"
}

List IDs associated with a specific system object:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/system/ldap/account?_queryId=query-all-ids"
{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 3,
  "result": [
    {
      "dn": "uid=jdoe,ou=People,dc=example,dc=com",
      "_id": "1ff2e78f-4c4c-300c-b8f7-c2ab160061e0"
    },
    {
      "dn": "uid=bjensen,ou=People,dc=example,dc=com",
      "_id": "fc252fd9-b982-3ed6-b42a-c76d2546312c"
    },
    {
      "dn": "uid=jimmysmith,ou=people,dc=example,dc=com",
      "_id": "07b46858-56eb-457c-b935-cfe6ddf769c7"
    }
  ]
}