Use a remote proxy to access data objects

You can proxy REST requests to another Advanced Identity Cloud tenant or IDM instance using the /external/idm/instanceName endpoint via the IDM remote proxy. This lets you treat any other tenant/IDM instance as a resource within the one you are managing.

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

The remote proxy acts as a REST client to the tenant/IDM instance; therefore, typical configurations for a remote proxy to operate (DNS resolution, network connectivity, SSL, and so on) are required.

Once you set up and configure the remote proxy, you can then:

Use it in a sync mapping
Call actions on it
Use it within scripts
Use it in any other way that you might use a resource

You can call any endpoint in the remote tenant/IDM instance using this proxy.

A few situations where this feature may be useful include:

Syncing data in a sandbox or development tenant into the staging environment (or from staging to production).
Syncing changes where there are geographically diverse data centers and they need to be kept in sync with one another.
Syncing data between existing self-managed IDM and a tenant/IDM instance.

The proxy does not support liveSync/implicit sync from the remote Advanced Identity Cloud resources. This means you are limited to using reconciliation when it comes to pulling data from a remote system.

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:

Get the configurations:

Request

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/config/"

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 (if the cert is signed by a CA that is not already in the truststore). For further information, refer to Self-managed SSL certificates.

Authenticate to another tenant or IDM instance

The manner in which you authenticate is based on how the remote tenant/IDM instance is configured to authenticate requests:

Remote proxy from one tenant to another.
- Authentication is completed via bearer authentication. Ensure you properly configure a client with the client credentials grant flow in the remote tenant before obtaining an access token.
  
  For the proxy to work, you must set client_secret_post as the Token Endpoint Authentication Method (tokenEndpointAuthMethod).
Remote proxy from a tenant to a self-managed IDM instance.
- If you need to remote proxy from a tenant to a self-managed IDM instance (or vice versa), you authenticate by the way in which the self-managed IDM is configured.
  
  If you connect to a self-managed IDM instance, basic authentication or bearer token authentication when IDM is configured to use rsFilter are supported.
  - basic authentication: Use a simple username/password binding to make the request.
  - bearer authentication: Ensure you properly configure a client with the client credentials grant flow in the remote instance before obtaining an access token.
    
    For the proxy to work, you must set client_secret_post as the Token Endpoint Authentication Method (tokenEndpointAuthMethod).

For either method, you must ensure the user authenticating has the required authorization role(s) to perform the necessary operations. Operations depend on the actions you intend to take on the remote tenant/IDM instance.

The authentication method you use determines the available properties:

Table 1. Properties available for authentication
Property	Required?	Definition
`enabled`	No	The enable state of the service. The 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.

For any request sent to the source server that includes an X-Requested-With header, the value of the header is set to RemoteIDMProxy.

Examples

The following subsections show examples of how to authenticate via basic and with bearer authentication.

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

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'https://<tenant-env-fqdn>/openidm/external/idm/platform/managed/user?_queryFilter=true'
{
  "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
}

Use the remote proxy in a sync mapping

To use the remote proxy in a synchronization mapping, add the mapping to your mapping configuration.

For example:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--data '{
  "mappings": [
    {
      "name": "onprem_user_to_fidc_alpha_user",
      "source": "external/idm/65/managed/user",
      "target": "external/idm/fidc/managed/alpha_user"
    }
  ]
}' \
--request PUT \
"https://<tenant-env-fqdn>/openidm/config/sync"

To verify the changes, get the mapping configuration.

For example:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/config/sync"

Use the remote proxy in a script

Once you have created a mapping, you can manipulate the remote Advanced Identity Cloud tenant or IDM instance via scripts.

For more information, refer to script functions.

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

PingOne Advanced Identity Cloud