Use a remote proxy to access data objects
You can proxy REST requests to another Advanced Identity Cloud tenant or self-managed IDM instance using the /external/idm/instanceName
endpoint through the IDM remote proxy. This lets you treat any other tenant or IDM instance as a resource within the one you’re managing. Learn more in How to determine the value for instanceName
.
The remote proxy acts as a REST client to the tenant or IDM instance. Typical configurations are required for a remote proxy to operate, such as DNS resolution, network connectivity, SSL, and so on.
After you set up and configure the remote proxy, you can:
-
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 or IDM instance using this proxy.
A few situations where this feature might 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 that need to be kept in sync with one another.
-
Syncing data between an existing self-managed IDM and a tenant or IDM instance.
The proxy doesn’t support liveSync or implicit sync from the remote Advanced Identity Cloud resources. You’re 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:
Requestcurl --location \ --header "Authorization: Bearer <access-token>" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ 'https://<tenant-env-fqdn>/openidm/config?_queryFilter=_id+sw+"external.idm/"'
-
Locate the external configuration:
Return{ "result": [ { "_id": "external.idm/name1", (1) "pid": "external.idm.29cd...f4a", "factoryPid": "external.idm" }, ... ] }
json1 In this example, the external configuration "_id": "external.idm/name1"
would be available as a remote system at theopenidm/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 certificate is signed by a CA that isn’t already in the truststore. Learn more in Self-managed certificates.
Authenticate to another tenant or IDM instance
The way you authenticate is based on how the remote tenant or IDM instance is configured to authenticate requests:
-
Remote proxy from one tenant to another.
-
Authentication is completed using
bearer
authentication. Ensure you configure a client with the client credentials grant flow in the remote tenant before you obtain 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 in the other direction, you authenticate using the method for which the self-managed IDM instance is configured.
If you connect to a self-managed IDM instance, Advanced Identity Cloud supports basic authentication or bearer token authentication if IDM is configured to use an rsFilter.
-
basic
authentication: Use a simple username and password binding to make the request. -
bearer
authentication: Ensure you configure a client with the client credentials grant flow in the remote instance before you obtain 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 roles to perform the necessary operations. Operations depend on the actions you intend to take on the remote tenant or IDM instance.
The authentication method you use determines the available properties:
Property | Required? | Definition |
---|---|---|
|
No |
The enable state of the service. The default is |
|
No |
The requested OAuth2 scope(s). |
|
No |
The scope delimiter to use. Defaults to space. |
|
Yes |
The authentication strategy to use. Either |
|
Yes |
The URL of the remote instance to relay the request to. |
|
With |
The basic authentication user name. |
|
With |
The basic authentication password. |
|
With |
The |
|
With |
The client secret used to request an access token from the token endpoint. |
|
With |
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 using basic
and bearer
authentication.
Basic authentication
{
"enabled" : true,
"authType" : "basic",
"instanceUrl" : "https://localhost:8443/openidm/",
"userName" : "openidm-admin",
"password" : "openidm-admin"
}
Bearer or OAuth2 authentication
{
"enabled" : true,
"authType" : "bearer",
"instanceUrl" : "https://fr-platform.iam.example.com/openidm/",
"clientId" : "idm-provisioning",
"clientSecret" : "password",
"scope" : "fr:idm:*",
"tokenEndpoint" : "https://fr-platform.iam.example.com/am/oauth2/realms/root/access_token",
"scopeDelimiter" : " "
}
For remote proxy connections, consider using granular permissions instead of default or privileged client IDs. Besides an access token, the For example:
json
|
REST request
curl \ --header "Authorization: Bearer <access-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 <access-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 <access-token>" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://<tenant-env-fqdn>/openidm/config/sync"
Use the remote proxy in a script
After you’ve created a mapping, you can manipulate the remote Advanced Identity Cloud tenant or IDM instance using a script function:
openidm.query("external/idm/fidc/managed/alpha_user", {"_queryFilter": "userName eq 'bjensen'"});