--- title: Remote proxy setup description: Step-by-step guide to configure a PingIDM remote proxy between instances using bearer (OAuth 2.0) or basic authentication component: pingidm version: 8.1 page_id: pingidm:objects-guide:remote-proxy-setup canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/remote-proxy-setup.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Data Object Model", "Synchronization"] section_ids: remote-proxy-setup-bearer: Set up bearer authentication (OAuth 2.0) remote-proxy-task1-oauth-client: "Task 1: Create an OAuth 2.0 client on the remote instance" remote-proxy-task2-static-mapping: "Task 2: Add a static user mapping on the remote instance" remote-proxy-task3-source-config: "Task 3: Create an external proxy on the local instance" remote-proxy-setup-basic: Set up basic authentication remote-proxy-task4-verify: Verify the proxy configuration --- # 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](remote-proxy-authentication-methods.html) 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)](#remote-proxy-setup-bearer). * If the remote instance is a self-managed PingIDM instance that doesn't authenticate through PingAM, set up [basic authentication](#remote-proxy-setup-basic). ## 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: 1. Log in to the AM console as an administrator. 2. In the realm you want to use, select Applications > OAuth 2.0 > Clients, and click Add Client. 3. Enter the following details: * Client ID: `` * Client secret: A generated secret value * Scopes: `fr:idm:*` 4. Click Create. 5. On the Advanced tab, set the following: * Token Endpoint Authentication Method: `client_secret_post` * Grant Types: Add `Client Credentials` 6. 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 *(tooltip: You can manage the authentication configuration over REST at the config/authentication endpoint, or directly in the conf/authentication.json file.)*: 1. Get the current authentication configuration: Request ```none curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/config/authentication" ``` Response ```json { "_id": "authentication", "rsFilter": { "clientId": "idm-resource-server", "clientSecret": "...", "tokenIntrospectUrl": "...", "scopes": [...], "subjectMapping": [...], "staticUserMapping": [] } } ``` 2. Add the static user mapping: | | | | - | --------------------------------------------------------------------------- | | | You must add the new mapping to the existing configuration, not replace it. | Request ```none 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:///openidm/config/authentication" \ --data '{ "_id": "authentication", "rsFilter": { ... existing properties ..., "staticUserMapping": [ ... existing mappings ..., { "subject": "", (1) "localUser": "internal/user/idm-provisioning", "roles": [ "internal/role/platform-provisioning" ] } ] } }' ``` | | | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **1** | 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 \. Self-managed PingIDM + PingAM (Core Token Service (CTS)-based, stateful tokens) Use the compound claim form (claimType!claimValue), for example (age!\). | Learn more about the `rsFilter`, `staticUserMapping`, and related properties in [Authenticate through AM](../auth-guide/rsfilter-auth.html). ### Task 3: Create an external proxy on the local instance On the local instance, create the external proxy configuration: Request ```none 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:///openidm/config/external.idm/" \ (1) --data '{ "enabled": true, "authType": "bearer", "instanceUrl": "https:///openidm/", (2) "clientId": "", "clientSecret": "", (3) "scope": ["fr:idm:*"], "tokenEndpoint": "https:///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/`. | | **2** | The `instanceUrl` must end with a trailing slash. | | **3** | Store the client secret in a [secret store](../security-guide/secret-stores.html) instead of using a plaintext value. | Response ```json { "enabled": true, "authType": "bearer", "instanceUrl": "https:///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 ```none 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:///openidm/config/external.idm/" \ (1) --data '{ "enabled": true, "authType": "basic", "instanceUrl": "https:///openidm/", (2) "userName": "openidm-admin", "password": "" (3) }' ``` | | | | ----- | -------------------------------------------------------------------------------------------------------------------------- | | **1** | This configuration defines the endpoint and is accessible at runtime using `/openidm/external/idm/`. | | **2** | The `instanceUrl` must end with a trailing slash. | | **3** | Store the password in a [secret store](../security-guide/secret-stores.html) instead of using a plaintext value. | Response ```json { "enabled": true, "authType": "basic", "instanceUrl": "https:///openidm/" } ``` ## Verify the proxy configuration Test that the proxy works by querying users from the remote instance: Request ```none 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:///openidm/external/idm//managed/user?_queryFilter=true&_pageSize=10" ``` Response ```json { "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.