Use a remote proxy to access data objects

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

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.

This feature does not support liveSync/implicit sync from the remote Identity Cloud resources.

This means you are limited to using reconciliation when it comes to pulling data from a remote system.

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 Configure a self-managed SSL certificate.

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.
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 to before obtaining an access token.

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. 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" : " "
}

Sample request

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'http://<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 \
"http://<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 \
"http://<tenant-env-fqdn>/openidm/config/sync"

Use the remote proxy in a script

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

For more information on the script functions, refer to the Scripting function reference.

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