Remote proxy setup

Follow these steps to configure a remote proxy between a local instance and a remote instance. This configuration allows the local instance to make API calls to the remote instance securely.

The setup steps depend on which authentication method the remote instance uses:

If the remote instance is fronted by PingAM, or is an Advanced Identity Cloud tenant, set up bearer authentication (OAuth 2.0).
If the remote instance is a self-managed PingIDM instance that doesn’t authenticate through PingAM, set up basic authentication.

Set up bearer authentication (OAuth 2.0)

Task 1: Create an OAuth 2.0 client on the remote instance

If the remote instance is fronted by PingAM, create an OAuth 2.0 client that the local instance uses to authenticate:

Log in to the AM console as an administrator.
In the realm you want to use, select Applications > OAuth 2.0 > Clients, and click Add Client.
Enter the following details:
- Client ID: <clientIDName>
- Client secret: A generated secret value
- Scopes: fr:idm:*
Click Create.
On the Advanced tab, set the following:
- Token Endpoint Authentication Method: client_secret_post
- Grant Types: Add Client Credentials
Click Save Changes.

Task 2: Add a static user mapping on the remote instance

The OAuth 2.0 client needs permissions to access PingIDM endpoints on the remote instance. If the remote instance authenticates through AM using the rsFilter, add a static user mapping to the authentication configuration:

Get the current authentication configuration:

Request

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<remote-instance-fqdn>/openidm/config/authentication"

Response

{
   "_id": "authentication",
   "rsFilter": {
      "clientId": "idm-resource-server",
      "clientSecret": "...",
      "tokenIntrospectUrl": "...",
      "scopes": [...],
      "subjectMapping": [...],
      "staticUserMapping": []
   }
}

Add the static user mapping:

You must add the new mapping to the existing configuration, not replace it.

Request

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match: *" \
--request PUT "https://<remote-instance-fqdn>/openidm/config/authentication" \
--data '{
  "_id": "authentication",
  "rsFilter": {
    ... existing properties ...,
    "staticUserMapping": [
      ... existing mappings ...,
      {
        "subject": "<clientIDName>", (1)
        "localUser": "internal/user/idm-provisioning",
        "roles": [
          "internal/role/platform-provisioning"
        ]
      }
    ]
  }
}'

The subject format depends on how the remote instance issues access tokens.

Remote instance type subject format

Advanced Identity Cloud (stateless JWTs)

Use the bare OAuth 2.0 client ID only, with no compound claim prefix, for example <clientIDName>.

Self-managed PingIDM + PingAM (Core Token Service (CTS)-based, stateful tokens)

Use the compound claim form (claimType!claimValue), for example (age!<clientIDName>).

Learn more about the rsFilter, staticUserMapping, and related properties in Authenticate through AM.

Task 3: Create an external proxy on the local instance

On the local instance, create the external proxy configuration:

Request

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request PUT "https://<local-instance-fqdn>/openidm/config/external.idm/<remote-instance-name>" \ (1)
--data '{
  "enabled": true,
  "authType": "bearer",
  "instanceUrl": "https://<remote-instance-fqdn>/openidm/", (2)
  "clientId": "<clientIDName>",
  "clientSecret": "<client-secret>", (3)
  "scope": ["fr:idm:*"],
  "tokenEndpoint": "https://<remote-instance-fqdn>/am/oauth2/realms/root/realms/alpha/access_token",
  "tokenEndpointAuthMethod": "client_secret_post",
  "scopeDelimiter": " "
}'

1	This configuration defines the endpoint and is accessible at runtime using `/openidm/external/idm/<remote-instance-name>`.
2	The `instanceUrl` must end with a trailing slash.
3	Store the client secret in a secret store instead of using a plaintext value.

Response

{
   "enabled": true,
   "authType": "bearer",
   "instanceUrl": "https://<remote-instance-fqdn>/openidm/"
}

Set up basic authentication

Use this method to connect to a self-managed PingIDM instance that doesn’t authenticate through PingAM. Basic authentication doesn’t require an OAuth 2.0 client or a static user mapping on the remote instance.

On the local instance, create the external proxy configuration:

Request

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request PUT "https://<local-instance-fqdn>/openidm/config/external.idm/<remote-instance-name>" \ (1)
--data '{
  "enabled": true,
  "authType": "basic",
  "instanceUrl": "https://<remote-instance-fqdn>/openidm/", (2)
  "userName": "openidm-admin",
  "password": "<password>" (3)
}'

1	This configuration defines the endpoint and is accessible at runtime using `/openidm/external/idm/<remote-instance-name>`.
2	The `instanceUrl` must end with a trailing slash.
3	Store the password in a secret store instead of using a plaintext value.

Response

{
   "enabled": true,
   "authType": "basic",
   "instanceUrl": "https://<remote-instance-fqdn>/openidm/"
}

Verify the proxy configuration

Test that the proxy works by querying users from the remote instance:

Request

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request GET "https://<local-instance-fqdn>/openidm/external/idm/<remote-instance-name>/managed/user?_queryFilter=true&_pageSize=10"

Response

{
   "result": [
      {
         "_id": "95b2b43c-621e-4bca-8a97-efc768f17751",
         "_rev": "00000000f20217df",
         "userName": "bjensen",
         "accountStatus": "active",
         "givenName": "Barbara",
         "sn": "Jensen",
         "mail": "bjensen@example.com"
      }
   ],
   "resultCount": 1,
   "pagedResultsCookie": null,
   "totalPagedResults": -1
}

If you get an error, review the following:

401 Unauthorized: Check OAuth 2.0 client credentials.
403 Forbidden: Verify the static user mapping is configured.
404 Not Found: Verify the configuration name and realm name.
500 Server Error: Check logs on both the local and remote instances.