Identity Cloud

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/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 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:

  1. Get the configurations:

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

      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 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'"});
Copyright © 2010-2024 ForgeRock, all rights reserved.