--- title: Use a remote proxy to access data objects description: 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. component: pingoneaic page_id: pingoneaic:idm-objects:data-rest-proxy canonical_url: https://docs.pingidentity.com/pingoneaic/idm-objects/data-rest-proxy.html keywords: ["Data Object Model", "Synchronization"] section_ids: determine-instancename-value: How to determine the value for instanceName remote-proxy-prereq: Prerequisites remote-proxy-auth: Authenticate to another tenant or IDM instance examples: Examples remote-proxy-basic-auth-example: Basic authentication remote-proxy-bearer-auth-example: Bearer or OAuth2 authentication remote-proxy-rest-request-example: REST request use_the_remote_proxy_in_a_sync_mapping: Use the remote proxy in a sync mapping use_the_remote_proxy_in_a_script: Use the remote proxy in a script --- # 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`](#determine-instancename-value). 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](../idm-synchronization/sync-types.html) 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: 1. Get the configurations: Request ```none curl --location \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ 'https:///openidm/config?_queryFilter=_id+sw+"external.idm/"' ``` 2. Locate the external configuration: Return ```json { "result": [ { "_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 certificate is signed by a CA that isn't already in the truststore. Learn more in [Self-managed certificates](../realms/server-certificates.html#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](../am-oauth2/oauth2-client-cred-grant.html) 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](https://docs.pingidentity.com/pingidm/8/auth-guide/rsfilter-auth.html). * `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](../am-oauth2/oauth2-client-cred-grant.html) 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](../idm-auth/authentication-and-roles.html) 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: **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 using `basic` and `bearer` authentication. ### Basic authentication ```json { "enabled" : true, "authType" : "basic", "instanceUrl" : "https://localhost:8443/openidm/", "userName" : "openidm-admin", "password" : "openidm-admin" } ``` ### Bearer or OAuth2 authentication ```json { "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 `clientID` must be granted the necessary permissions through a `staticUserMapping` in the authentication configuration *(tooltip: You can manage the authentication configuration over REST at the config/authentication endpoint.)* or by adding equivalent role assignments in the Advanced Identity Cloud admin console.For example:```json { "staticUserMapping": [ { "localUser": "internal/user/openidm-admin", "roles": [ "internal/role/openidm-authorized", "internal/role/openidm-admin" ], "subject": "self-managed-idm", (1) "userRoles": "authzRoles/*" } ] } ```1 The subject should be the clientID used by the remote proxy. | ### REST request ``` curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ 'https:///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](../idm-synchronization/mappings.html), add the mapping to your mapping configuration *(tooltip: You can manage the mapping configuration over REST at the config/sync endpoint.)*. For example: ``` curl \ --header "Authorization: Bearer " \ --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:///openidm/config/sync" ``` To verify the changes, get the mapping configuration *(tooltip: You can manage the mapping configuration over REST at the config/sync endpoint.)*. For example: ``` curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///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](../idm-scripting/scripting-func-engine.html): ```javascript openidm.query("external/idm/fidc/managed/alpha_user", {"_queryFilter": "userName eq 'bjensen'"}); ```