PingIDM 7.5.0

Access data objects by remote proxy

You can proxy REST requests to a remote IDM or Advanced Identity Cloud instance using the openidm/external/idm/instanceName endpoint.

For more information on determining the exact value for instanceName, refer to How to determine the value for instanceName.

This functionality lets you treat any other IDM or Advanced Identity Cloud instance as a resource within the one you are managing. You can then use it in a sync mapping, call actions on it, use it within scripts, or use it in any other way that you might use a resource in IDM. You can call any endpoint in the remote IDM system using this proxy.

A few situations where this feature may be useful include:

  • Situations where some, but not all, data needs to be migrated from an older version to a newer release.

  • Situations where a development or testing environment has data that needs to be synced into the production environment.

  • Situations where data is deployed in geographically diverse data centers and changes need to be kept in sync with one another.

  • Situations where a new instance needs to sync data between existing on-premises and cloud instances.

This feature does not support liveSync/implicit sync from the remote IDM resources. This means that you will be limited to using recon when it comes to pulling data from a remote system.

If requests sent to the source server include an X-Requested-With header, the value of the header will be set to RemoteIDMProxy.

How to determine the value for instanceName

The instanceName is a fragment of the external configuration’s name. You can determine the value for instanceName using REST or the filesystem:

Using the filesystem

  1. Go to /path/to/openidm/conf/.

  2. Locate the file named external.idm-instanceName.json.

    For example, a file named external.idm-name1.json would be available as a remote system at the openidm/external/idm/name1 endpoint.

Using REST

  1. Get the configurations:

    Request
    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://localhost:8443/openidm/config/"

  2. Locate the external configuration:

    Return
    {
  "_id": "",
  "configurations": [
    ...
    {
      "_id": "emailTemplate/welcome",
      "pid": "emailTemplate.212e...f7a",
      "factoryPid": "emailTemplate"
    },
    ...
    {
      "_id": "external.idm/name1", (1)
      "pid": "external.idm.29cd...f4a",
      "factoryPid": "external.idm"
    },
    ...
  ]
}
    1 In this example, the external configuration "_id": "external.idm/name1" would be available as a remote system at the openidm/external/idm/name1 endpoint.

Prerequisites

To connect to a remote instance over SSL, you must import the remote instance’s server certificate into your local instance’s truststore. For example:

keytool \
-import \
-alias fr-platform \
-keystore security/truststore \
-file ~/fr-platform.pem

Mapping

To use the remote IDM proxy in a synchronization mapping, add the following to your sync.json file or individual mapping file (updating the values as necessary):

{
  "name" : "onprem_user_to_fidc_alpha_user",
  "source" : "external/idm/65/managed/user",
  "target" : "external/idm/fidc/managed/alpha_user"
}

Authentication

Authentication against the remote IDM instance is supported via basic authentication, or bearer token authentication when IDM is configured to use rsFilter. The authentication strategy determines some of the parameters required for the request.

Property Required? Definition

enabled

No

The enable state of the service. Default is true.

scope

No

The requested OAuth2 scope(s).

scopeDelimiter

No

The scope delimiter to use. Defaults to space.

authtype

Yes

The authentication strategy to use. Either basic or bearer.

instanceUrl

Yes

The URL of the remote instance to relay the request to.

userName

With basic auth

The basic authentication user name.

password

With basic auth

The basic authentication password.

clientId

With bearer auth

The clientId used to request an access token from the token endpoint.

clientSecret

With bearer auth

The client secret used to request an access token from the token endpoint.

tokenEndpoint

With bearer auth

The OAuth2 token endpoint.

Examples

Basic authentication

{
  "enabled" : true,
  "authType" : "basic",
  "instanceUrl" : "https://localhost:8443/openidm/",
  "userName" : "openidm-admin",
  "password" : "openidm-admin"
}

Bearer/Oauth2 authentication

{
  "enabled" : true,
  "authType" : "bearer",
  "instanceUrl" : "https://fr-platform.iam.example.com/openidm/",
  "clientId" : "idm-provisioning",
  "clientSecret" : "password",
  "scope" : [ ],
  "tokenEndpoint" : "https://fr-platform.iam.example.com/am/oauth2/realms/root/access_token",
  "scopeDelimiter" : " "
}

REST request

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--insecure \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'https://localhost:8443/openidm/external/idm/platform/managed/user?_queryFilter=true'
Return
{
  "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
}

Script

openidm.query("external/idm/fidc/managed/alpha_user", {"_queryFilter": "userName eq 'bjensen'"});