PingOne Advanced Identity Cloud

Manage Proxy Connect using the API

You can find background information on Proxy Connect in PingOne Advanced Identity Cloud in Restrict network access with Proxy Connect.

Proxy Connect API endpoints

Proxy Connect provides these Advanced Identity Cloud API endpoints:

  • Rules API endpoint (/environment/proxy-connect)

    • Use GET to view the header and IP rulesets and determine if they are active.

    • Use PUT to update the header and IP rulesets and activate or deactivate the rulesets.

    This endpoint supersedes the deprecated endpoints listed in the next section. It lets you configure header and IP rulesets at the same time and also lets you configure the status field proxyStatus to give more control over the behavior of Proxy Connect.

    The status field proxyStatus has two states you can set:

    Status Description

    OPEN

    Proxy Connect has no rules configured, and traffic to your tenant environment’s TLS load balancer is unrestricted.

    FILTERING

    Proxy Connect has at least one rule configured, and traffic to your tenant environment’s TLS load balancer is restricted by any configured rules.
    A third status, BLOCKING, is reserved for future use.

Deprecated

  • Header rules API endpoint (/environment/proxy-connect/header-rules)

    • Use GET to view the header ruleset and determine if the ruleset is active.

    • Use PUT to update the header ruleset and activate or deactivate the ruleset.

  • IP Address rules API endpoint (/environment/proxy-connect/ip-rules)

    • Use GET to view the IP ruleset and determine if the ruleset is active.

    • Use PUT to update the IP ruleset and activate or deactivate the ruleset.

These endpoints are deprecated. Learn more in Deprecation notices. If you still need to use them before their end-of-life date, they’re documented in these PDFs:

Authenticate to Proxy Connect API endpoints

To authenticate to Proxy Connect API endpoints, use an access token created with one of the following scopes:

Scope Description

fr:idc:proxy-connect:*

Full access to Proxy Connect API endpoints. Use this scope to view, create, activate, deactivate, or delete rules.

fr:idc:proxy-connect:read

Read-only access to Proxy Connect API endpoints. Use this scope if you only need to View default rulesets or View configured rulesets.

fr:idc:proxy-connect:write

Write access to Proxy Connect API endpoints. Use this scope to create, activate, deactivate, or delete rules.

Prerequisite actions for accessing a tenant when rulesets are configured

If you already have any HTTP header or IP rules configured for a tenant environment, you’ll need to meet the requirements of the rules to access the tenant successfully.

The prerequisite actions aren’t required if you configured a proxy service to access your tenant or if you configured Secure Connect and can access your tenant from a private network.

  1. Consult with your team to find out what header rules are configured for the environment:

    1. If header rules are configured, you need the name and value of a configured security header.

    2. To access the tenant using a browser, configure a browser extension to add the security header to all browser requests. For example, the SimpleModifyHeaders extension lets you modify headers for Chrome and Firefox:

      simple modify headers configuration

    3. To access the tenant using the API, add the security header to all cURL requests using the format:

      --header '<security-header-name>: <security-header-value>'

      For example:

      --header 'X-Security-Header: f1drybngmzqj5loposddd5p98z886jp9'

  2. Consult with your team to find out what IP rules are configured for the environment:

    1. If IP rules are configured, your IP address needs to be in one of the configured CIDR ranges. To change your IP address, you might need to join your company’s VPN, or your team might need to add your IP address to the IP rules configuration.

    2. Run all browser and API requests from a configured IP address.

View default rulesets

By default, the header and IP rulesets in each of your tenant environments are inactive. You can view the default ruleset configurations using the API without adding a security header or using a particular IP address.

In any tenant environment (where the header and IP rulesets are inactive):

  1. Get an access token created with the fr:idc:proxy-connect:read scope.

  2. Get the ruleset configuration from the /environment/proxy-connect endpoint:

    $ curl \
--request GET 'https://<tenant-env-fqdn>/environment/proxy-connect' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json'
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token.

    The response shows the default ruleset configuration:

    Show response 
    {
  "ipRules": {
    "enabled": false, (1)
    "ipRanges": null, (2)
    "requestStatus": "SUCCESS" (3)
  },
  "headerRules": {
    "enabled": false, (4)
    "headers": null, (5)
    "requestStatus": "SUCCESS" (6)
  },
  "proxyStatus": "OPEN", (7)
  "requestStatus": "SUCCESS" (8)
}
    1 The IP ruleset isn’t active.
    2 The IP ruleset contains no rules.
    3 The IP ruleset is synchronized with the environment’s TLS load balancer.
    4 The header ruleset isn’t active.
    5 The header ruleset contains no rules.
    6 The header ruleset is synchronized with the environment’s TLS load balancer.
    7 Proxy Connect isn’t filtering or blocking any traffic to the environment’s TLS load balancer.
    8 The ruleset configuration is synchronized with the environment’s load balancer.

View configured rulesets

If the header or IP rulesets in a tenant environment have been activated, API requests return a 404 response unless you use a particular IP address and/or add a security header to your API requests.

In any tenant environment (where the header or IP rulesets are active):

  1. Complete the Prerequisite actions for accessing a tenant when rulesets are configured.

  2. Get an access token created with the fr:idc:proxy-connect:read scope.

  3. Get the ruleset configuration from the /environment/proxy-connect endpoint:

    $ curl \
--request GET 'https://<tenant-env-fqdn>/environment/proxy-connect' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json' \
--header '<security-header-name>: <security-header-value>' (3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token.
    3 (Optional) Review the prerequisite actions. If necessary, add an existing security header to your request; for example:

    --header 'X-Security-Header: f1drybngmzqj5loposddd5p98z886jp9'

    The response shows your custom configuration, which will be similar to this:

    Show response 
    {
  "ipRules": {
    "enabled": true, (1)
    "ipRanges": ["1.2.3.4/32"], (2)
    "requestStatus": "SUCCESS" (3)
  },
  "headerRules": {
    "enabled": true,  (4)
    "headers": [
      {"header": "X-Security-Header", "value": "f1drybngmzqj5loposddd5p98z886jp9"} (5)
    ],
    "requestStatus": "SUCCESS" (6)
  },
  "proxyStatus": "FILTERING", (7)
  "requestId": "ag-U9rQJd8O", (8)
  "requestStatus": "SUCCESS" (9)
}
    1 The IP ruleset is active.
    2 The IP ruleset contains one rule. Requests from a third-party service must originate from an IP address in the specified CIDR range to be classed as a valid request.
    3 The IP ruleset is synchronized with the environment’s TLS load balancer.
    4 The header ruleset is active.
    5 The header ruleset contains one rule. Requests from a third-party service must include an X-Security-Header HTTP security header (set with the specified value) to be classed as a valid request.
    6 The header ruleset is synchronized with the environment’s TLS load balancer.
    7 Proxy Connect is actively filtering traffic to the environment’s TLS load balancer.
    8 The last update to the ruleset configuration was assigned a requestId of "ag-U9rQJd8O".
    9 The ruleset configuration is synchronized with the environment’s load balancer.

Create or update rulesets

Create or update the header and IP rulesets in a tenant environment to configure Proxy Connect.

Test ruleset configuration updates on a lower environment before you update your production environment and ensure that any automated scripts aren’t affected by your changes.

In any tenant environment:

  1. Ensure the tenant environment is configured to use outbound static IP addresses.

  2. Complete the Prerequisite actions for accessing a tenant when rulesets are configured.

  3. Get an access token created with the fr:idc:proxy-connect:write scope.

  4. Update the ruleset configuration:

    1. Review the existing ruleset configuration. Learn more in:

    2. Replace the existing ruleset configuration with your own ruleset configuration:

      $ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/proxy-connect' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json'
--header '<security-header-name>: <security-header-value>' \ (3)
--data '{
  "ipRules": <ip-rules-json>, (4)
  "headerRules": <header-rules-json>, (5)
  "proxyStatus": "OPEN|FILTERING" (6)
}'
      1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
      2 Replace <access-token> with the access token.
      3 (Optional) Review the prerequisite actions. If necessary, add an existing security header to your request. For example:

      --header 'X-Security-Header: f1drybngmzqj5loposddd5p98z886jp9'
      4 (Optional) Replace <ip-rules-json> with a JSON object containing an enabled status and an ipRules array of CIDR ranges. For example: 
      {
  "enabled": true,
  "ipRules": ["1.2.3.4/32", "2.3.2.1/32"]
}
      5 (Optional) Replace <header-rules-json> with a JSON object containing an enabled status and a headers array of security header key-value objects. For example: 
      {
  "enabled": true,
  "headers": [
    {"header": "X-Security-Header", "value": "f1drybngmzqj5loposddd5p98z886jp9"},
    {"header": "X-Security-Header2", "value": "2ey9ant69h3021b49vvdl8qnww6rmj3y"}
  ]
}
      6 Set a proxyStatus value consistent with the rulesets you have defined:

      • Set the value FILTERING if you have defined any IP address or header rulesets.

      • Set the value OPEN if you haven’t defined any rulesets.

      If you set a proxyStatus value that isn’t consistent with the rulesets you have defined, the request returns the following error:

      {
  "code": 400,
  "message": "failed to validate proxy-connect status"
}
      Show response 
      {
  "ipRules": {
    "enabled": true, (1)
    "ipRanges": ["1.2.3.4/32", "2.3.2.1/32"], (2)
    "requestStatus": "PENDING" (3)
  },
  "headerRules": {
    "enabled": true, (4)
    "headers": [
      {"header": "X-Security-Header", "value": "f1drybngmzqj5loposddd5p98z886jp9"}, (5)
      {"header": "X-Security-Header2", "value": "2ey9ant69h3021b49vvdl8qnww6rmj3y"} (5)
    ],
    "requestStatus": "PENDING" (6)
  },
  "proxyStatus": "FILTERING", (7)
  "requestId": "ag-vnYPhgaC", (8)
  "requestStatus": "PENDING" (9)
}
      1 The IP ruleset is active.
      2 The IP ruleset contains two rules. Requests from a third-party service must originate from an IP address in one of the specified CIDR ranges to be classed as a valid request.
      3 The update to the IP ruleset isn’t synchronized with the environment’s load balancer yet.
      4 The header ruleset is active.
      5 The header ruleset contains two rules. Requests from a third-party service must include a X-Security-Header or X-Security-Header2 HTTP security header (set with the specified value) to be classed as a valid request.
      6 The update to the header ruleset isn’t synchronized with the environment’s load balancer yet.
      7 Proxy Connect is actively filtering traffic to the environment’s TLS load balancer.
      8 The update to the ruleset was assigned a requestId of "ag-vnYPhgaC".
      9 The update to the ruleset configuration isn’t synchronized with the environment’s load balancer yet.

    3. An asynchronous process updates the ruleset configuration in the environment’s load balancer. This process can take up to 10 minutes to complete.

      To check when the asynchronous process has completed, poll the /environment/proxy-connect endpoint until the requestStatus keys in the response change from PENDING to SUCCESS.

      $ curl \
--request GET 'https://<tenant-env-fqdn>/environment/proxy-connect' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json' \
--header '<security-header-name>: <security-header-value>' (3)
      1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
      2 Replace <access-token> with the access token.
      3 (Optional) Review the prerequisite actions. If necessary, add an existing security header to your request. Otherwise, if you are setting header rules for the first time, add one of the new security headers to your request. For example:

      --header 'X-Security-Header: f1drybngmzqj5loposddd5p98z886jp9'

      When the asynchronous process has completed and updated the ruleset configuration in the environment’s load balancer, the response should look like this:

      Show response 
      {
  "ipRules": {
    "enabled": true,
    "ipRanges": ["1.2.3.4/32", "2.3.2.1/32"],
    "requestStatus": "SUCCESS"
  },
  "headerRules": {
    "enabled": true,
    "headers": [
      {"header": "X-Security-Header", "value": "f1drybngmzqj5loposddd5p98z886jp9"},
      {"header": "X-Security-Header2", "value": "2ey9ant69h3021b49vvdl8qnww6rmj3y"}
    ],
    "requestStatus": "SUCCESS"
  },
  "proxyStatus": "FILTERING",
  "requestId": "ag-vnYPhgaC",
  "requestStatus": "SUCCESS"
}

Deactivate rulesets

To deactivate rulesets:

  • Follow the instructions in Create or update rulesets.

  • In step 4b, supply the --data option with this payload:

    {
  "ipRules": {"enabled": false, "ipRanges": []},
  "headerRules": {"enabled": false, "headers": []},
  "proxyStatus": "OPEN"
}