PingAuthorize

Connecting a service

Connect PingAuthorize to external services to define data integrations.

Service connections in PingAuthorize enable you to augment authorization events with real-time data. For example, you might use signals obtained from a risk service connection in a policy that determines whether a device requires step-up authentication.

Steps

  1. In the Policy Editor, go to Trust Framework.

  2. Click the Services tab, click the icon, and then select Add new Service.

  3. Enter a unique Name for the service.

    Periods (.) are not allowed in the name.

  4. (Optional) Enter a Description of the service’s purpose.

    The description is only visible on the Services tab, but it can help policy authors understand how to use services in policies.

  5. (Optional) To nest the service under a parent in the tree, in the Parent list, select a parent service.

    Nesting helps group related services together. You can move the service to another location in the tree by selecting a different parent service. To remove nesting, click the Delete icon and leave Parent blank.

  6. Select a Service Type.

    Choose from:

    • None: This is for a parent service. Nest other services under a parent to help organize services in the tree structure. There are no additional settings to complete for this type of service.

    • Database: Connects to relational databases and retrieves information through SQL queries. Learn more about database service settings in Database services.

    • HTTP: Connects to HTTP endpoints accessible over the public internet. Learn more about HTTP service settings in HTTP services.

    • LDAP: Connects to LDAP sources and retrieves information through database queries. Learn more about LDAP service settings in LDAP services.

  7. (Optional) In the Value Settings section, define the data Type for the data returned by the service, and select the Secrets checkbox to encrypt that data in PingAuthorize logs.

    Depending on which mode you’ve configured for PingAuthorize, service data secrets are recorded in one of these logs:

    • Embedded PDP mode: The service data values are encrypted in PingAuthorize/logs/policy-decision.log.

    • External PDP mode: The service data values are encrypted in PingAuthorize-PAP/logs/decision-audit.log.

    To decrypt a service’s data values, run the following command:

    'echo -n "RSNH/SPsNJSFQyyLSxdKsw==" | base64 -d | openssl enc -aes-128-ecb -d -K "54655374506153735068526153653939"

    In the previous example, RSNH/SPsNJSFQyyLSxdKsw== represents the encrypted service value string, and 54655374506153735068526153653939 represents the encryption key in hexadecimal. By default, the encryption key is TeStPaSsPhRaSe99 and cannot be changed.

  8. (Optional) In the Timeout and Retry section, configure the following properties:

    • Request Timeout: The time that PingAuthorize waits, in milliseconds, for a service request to complete.

      The default timeout is 2000. If the timeout elapses before there is a successful service response, the service request is canceled, resulting in a timeout error.

    • Number of retries: The number of times that PingAuthorize attempts a service request again when the initial request fails or times out. To try the service request only once, set this value to 0.

      If the service responds with a 4xx error, PingAuthorize won’t attempt any retries.

    • Retry Strategy: The approach that PingAuthorize uses when retrying service requests.

      • Fixed Interval (default): PingAuthorize waits for the specified retry delay between service requests.

      • Exponential Backoff: PingAuthorize uses the specified retry delay as a base and waits for an exponentially increasing amount of time between service requests.

    • Retry Delay: The time that PingAuthorize waits, in milliseconds, between service requests.

      • For fixed interval retries, PingAuthorize waits this number of milliseconds between each service request.

      • For exponential backoff retries, PingAuthorize multiplies this number by 2^n, where n is the number of retries already attempted.

        For example, if the retry delay is 1000 milliseconds, PingAuthorize makes the initial service request, then waits 1000 milliseconds before making a second request, 2000 milliseconds before making a third request, and so on.

    • Delay Jitter: The amount of variability, as a percentage, that PingAuthorize applies to the retry delay between each service request.

      Delay jitter reduces the chance of synchronized retries and cascading service failures.

      If this value is set to 10% and the retry delay is set to 1000 milliseconds with exponential backoff, the delays in the previous example would be 1000±100 milliseconds, 2000±100 milliseconds, 4000±100 milliseconds, and so on.

      If this value is set to 10% and the retry delay is set to a fixed interval of 1000 milliseconds, PingAuthorize waits 1000±100 milliseconds before making a second request, 1000±100 milliseconds before making a third request, and so on.

  9. (Optional) In the Rate Limits section, enter a Requests per Second value to change the maximum number of requests that decision points can make to the service per second.

    The default value is 1000000.

  10. (Optional) Configure the Circuit Breaker.

    Circuit breakers enhance system resilience by preventing request overload. When enabled, circuit breakers monitor service calls, temporarily halt requests to services that appear unavailable, and then carefully test those services for recovery. Circuit breakers can be open (blocking service requests), half-open (allowing test service requests), or closed (allowing service requests).

    Circuit breaker functionality is intended only for service requests made by the PingAuthorize Server in embedded PDP mode.
    Screen capture of the service’s Circuit Breaker settings.

    1. Select the Enable Circuit Breaker checkbox.

    2. For Failure Threshold, enter the number of consecutive failed service calls required to open the circuit breaker.

      When the breaker is open, all requests to the service are immediately blocked.

    3. For Reset delay, enter the number of seconds the circuit breaker should wait in an open state before transitioning to a half-open state.

      When the breaker is half-open, the system allows a limited number of requests to the service, testing if the underlying issue has been resolved before fully closing the breaker.

    4. For Success Threshold, enter the number of consecutive successful service calls required to close the circuit breaker.

      When the breaker is closed, the service is considered healthy and all service requests are allowed to pass through normally. If requests to the service fail before the success threshold is met, the breaker re-opens.

      The Debug Trace logger records messages indicating the current state of each circuit breaker. Learn more in Circuit breaker logging.

  11. (Optional) Enable caching for the service.

    Caching improves system performance by storing data returned from a service and reusing it on subsequent service requests until the cache expires. Learn more in Service caching.

    1. Select the Enable Caching checkbox.

    2. For the Time to Live, enter the number of minutes that you want to store data retrieved from the service in the cache.

      Screen capture of the Cache Settings section of a service with the Enable Caching checkbox selected.

      The maximum time to live is 1440 minutes or 1 day.

    3. (Optional) Click Header and select headers to exclude from the cache key.

      Screen capture of the Cache Settings section of a service with the Enable Caching checkbox selected and an example header exclusion

      Because the service cache is invalidated by any changes to the cache key, removing headers preserves the validity of the cache even when values of those headers change.