PingAuthorize

HTTP services

Configure HTTP settings to connect PingAuthorize to an HTTP service.

Before you connect to an HTTP service, you can add attributes that store values for service settings, such as the endpoint URL for an HTTP request. Storing settings as attributes is useful if the values are dynamic or if you want to use different values during testing.

If the service requires OAuth 2.0 Client Credentials authentication, you must add an attribute that stores the external service’s client secret before you configure service settings. You can also add attributes that store other client credentials, such as the client ID and token endpoint.

After configuring the service, test the service connection. To make the service response available in policies, add attributes that resolve against the service and process the response to extract required values.

HTTP settings

HTTP service requests can send and receive text, JSON, and XML content.

Screen capture showing the Service Type, URL, HTTP Method, Body, and Authentication HTTP service settings.
HTTP settings
Setting Description
URL

The URL for the REST endpoint that the PDP accesses in the HTTP request

To include an attribute anywhere in the URL, wrap the full name of the attribute in double curly brackets.

Because no escaping of attribute values takes place, make certain that this action is completed in the attribute definition to prevent non-valid characters in the URL.

HTTP Method

The action performed in the HTTP request

Content Type

The media type of the content in the HTTP request

Body

The body to send with the HTTP request

You can include attributes anywhere in the body, with no escaping, by wrapping the full name of the attribute in double curly brackets.

Authentication

The HTTP authentication method for the authorization header sent with the HTTP request. HTTP authentication methods are described below.

HTTP authentication methods

HTTP service requests can use no authentication, basic authentication with a username and password, a bearer token, or the OAuth 2.0 Client Credentials flow.

None

With this method, no authorization header is sent with the HTTP request. This is the default option.

Basic

For basic authentication, provide a username and password.

Screen capture showing the Username and Password settings for Basic authentication
Bearer Token

For bearer authentication with a static token, select an attribute that stores the authorization token to send with the HTTP request.

Screen capture showing the Token selection list for Bearer Token authentication
OAuth 2.0 (Client Credentials)

To reduce configuration complexity and time to production when connecting to HTTP services that require OAuth authentication, configure client credentials to be exchanged for an access token.

Screen capture showing the Token Endpoint, Scope, Client Id, and Client Secret settings for OAuth 2.0 Client Credentials authentication

PingAuthorize manages this authentication process as follows:

  1. PingAuthorize requests an access token for the external service by sending client credentials, including any scopes, in a POST request to the authorization server’s token endpoint. Credentials are sent in the request body.

  2. The authorization server validates the client credentials and provides an access token, which PingAuthorize caches. When the external service no longer accepts this token, PingAuthorize sends another POST request to the token endpoint to obtain a new one.

  3. In an HTTP service request, PingAuthorize provides the access token in the Authorization header, authenticates with the HTTP service, and retrieves the requested information from the service.

Before you configure the following settings, add an attribute that stores the client secret. You can also add attributes that store other client credentials.

  • Token Endpoint: The token endpoint URL for the authorization server that grants an access token. For example, https://{domain}/oauth*/token.

  • Client Id: A unique string representing the client identifier. This value can be either a constant or an interpolated attribute to resolve the value at runtime.

  • Client Secret: A Trust Framework attribute that resolves to the client secret.

  • Scope (optional): A comma-separated list of scopes representing the scope of the access request.

  • Advanced OAuth Settings (optional): A list of custom key-value pairs representing additional parameters sent in the body of the token endpoint request. This level of customization is useful when integrating with authorization servers that enforce specific configuration constraints.

    The keys are fixed strings, but their values can be constants or attribute values. To switch between constant and attribute, toggle C / A.

    Advanced OAuth settings have the following constraints:

    • You can define up to 10 key-value pairs.

    • Keys cannot contain spaces in any position.

    • You cannot use any of the following values as a key (case-sensitive):

      • client_id

      • client_secret

      • scope

      • grant_type

Headers

You can add any number of custom headers to the request. The header names are fixed strings, but their values can be constants or attribute values. To switch between constant and attribute, toggle C / A, which is next to a header value.

To prevent invalidation of HTTP service response caches caused by changes to the cache key, you can exclude certain headers that you expect to change from service cache entries. Learn more in Connecting a service and Service caching.

Certificate validation

With certificate validation, you can define TLS and Mutual-TLS (M-TLS) certificates and keys when connecting to the TLS (or SSL) based service.

When using external PDP mode, you can declare local file-based trust stores and key stores by providing an options file during setup. Learn more in Specifying custom configuration with an options file.

When using embedded PDP mode, you can declare local file-based trust stores and key stores by assigning trust manager providers and key manager providers to the Policy Decision Service. Learn more in Deploy policies in a production environment.

Server (TLS)

Applies when validating the certificate or certificate chain sent from the server. You have three options when validating a server certificate:

  • No Validation

    Skips validating the server certificates and initiates connection without any restriction.

  • Default

    This option is the default for Server (TLS).

    Uses the default trust store provided by the runtime environment.

    Use this if you’re trying to connect to a service that has a certificate issued from a valid certificate authority.

  • Custom

    Allows the user to define a custom certificate or certificate chain that is stored in a trust store:

    • Truststore name

      The name given to the trust store in configuration.yml.

    • Alias

      Certificates in the trust stores are mapped by alias. You must set the alias in the trust store to specify which certificate to use for validation.

      Attributes can be interpolated anywhere in the value.

    • Alias password

      If the certificate is password protected, it might need to provide the password.

      Attributes can be interpolated anywhere in the value.

Client (M-TLS)

Some services might require the client to provide a client certificate when initializing the connection. To provide a client certificate, enable this setting and provide a custom key store to be sent to the service:

  • Keystore name

    The name given to the key store in configuration.yml.

  • Alias

    Key-value pairs and the certificate entry in the key stores are mapped by alias. You must set the alias in the key store to specify which entry to use for validation.

    Attributes can be interpolated anywhere in the value.

  • Alias password

    If the certificate entry is password protected, it might need to provide the password.

    Attributes can be interpolated anywhere in the value.