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:

Request

curl --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"
    },
    ...
  ]
}
```
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.

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:

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

{
  "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 clientID must be granted the necessary permissions through a staticUserMapping in the authentication configuration or by adding equivalent role assignments in the Advanced Identity Cloud admin console.

For example:

{
  "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 <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'"});

PingOne Advanced Identity Cloud

Use a remote proxy to access data objects

How to determine the value for instanceName

Prerequisites

Authenticate to another tenant or IDM instance

Examples

Basic authentication

Bearer or OAuth2 authentication

REST request

Use the remote proxy in a sync mapping

Use the remote proxy in a script

How to determine the value for `instanceName`