PingIDM

Remote proxy advanced usage

In addition to basic remote proxy calls, you can manage external configurations directly through the REST API. The following examples show how to use REST access paths to query data through the proxy, and how to list, view, and delete remote proxy configurations.

REST access paths

For PingIDM systems, the configuration file is named external.idm-<remote-instance-name>.json. This configuration is exposed over REST through two distinct router endpoints:

  • /openidm/config/external.idm/<remote-instance-name> is the config management path, used to create, read, and delete the proxy configuration. The _id returned by /openidm/config queries always uses this dot form.

  • /openidm/external/idm/<remote-instance-name>/ is the runtime data access path, used to proxy requests through to the remote instance.

Use the runtime data access path (slash form) to query data through the proxy.

For example:

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<local-instance-fqdn>/openidm/external/idm/<remote-instance-name>/managed/user?_queryFilter=true"
Response
{
  "result": [
    {
      "_id": "95b2b43c-621e-4bca-8a97-efc768f17751",
      "_rev": "00000000f20217df",
      "userName": "testUser",
      "accountStatus": "active",
      "givenName": "Test",
      "sn": "User",
      "mail": "testUser@test.com"
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

List all external configurations

Use the config management path (dot form) to list external configurations.

For example:

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'https://<local-instance-fqdn>/openidm/config?_queryFilter=_id+sw+"external.idm"'
Response
{
  "result": [
    {
      "_id": "external.idm/<remote-instance-name>",
      "enabled": true,
      "authType": "bearer",
      "instanceUrl": "https://<remote-instance-fqdn>/openidm/",
      "clientId": "<clientIDName>",
      "clientSecret": {
        "$crypto": {
          "type": "x-simple-encryption",
          "value": { <encryptedValue> }
        }
      },
      "scope": [
        "fr:idm:*"
      ],
      "tokenEndpoint": "https://<remote-instance-fqdn>/am/oauth2/realms/root/realms/alpha/access_token",
      "tokenEndpointAuthMethod": "client_secret_post",
      "scopeDelimiter": " "
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "EXACT",
  "totalPagedResults": 1,
  "remainingPagedResults": -1
}

Get a specific external configuration

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<local-instance-fqdn>/openidm/config/external.idm/<remote-instance-name>"

Delete an external configuration

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<local-instance-fqdn>/openidm/config/external.idm/<remote-instance-name>"