Authenticating to the JSON PDP API

The JSON PDP API can require a client to authenticate to it by using a shared secret.

To define shared secrets, use JSON PDP API Shared Secret configuration objects. To manage shared secrets, use the JSON PDP API HTTP Servlet Extension.

Creating a shared secret

Define the authentication credentials that the JSON PDP API might require a client to present.

Steps

To create a shared secret, run the following example dsconfig command, substituting values of your choosing.

Example:

PingAuthorize/bin/dsconfig create-authorization-policy-decision-shared-secret \
  --secret-name "Shared Secret A" \
  --set "shared-secret:secret123"

The shared-secret property sets the value that the JSON PDP API requires the client to present. After you set this value, it is no longer visible.
The secret-name property is a label that allows an administrator to distinguish one JSON PDP API Shared Secret from another.

To update the shared-secrets property, run the following example dsconfig command.

Example:
PingAuthorize/bin/dsconfig set-http-servlet-extension-prop \ --extension-name "JSON PDP API" \ --add "shared-secrets:Shared Secret A"
A new JSON PDP API Shared Secret is not used until the shared-secrets property of the JSON PDP API HTTP Servlet Extension is updated.

Deleting a shared secret

You can remove a shared secret from use or delete it entirely.

Steps

To remove a JSON PDP API Shared Secret from use, run the following example dsconfig command, substituting values of your choosing.

Example:

{pingauthorize}/bin/dsconfig set-http-servlet-extension-prop \
  --extension-name "JSON PDP API" \
  --remove "shared-secrets:Shared Secret A"

To delete a JSON PDP API Shared Secret, run the following example dsconfig command.

Example:

{pingauthorize}/bin/dsconfig delete-authorization-policy-decision-shared-secret \
  --secret-name "Shared Secret A"

Rotating shared secrets

To avoid service interruptions, the JSON PDP API allows multiple, distinct shared secrets to be accepted at the same time.

You can configure a new shared secret that the JSON PDP API accepts alongside an existing shared secret. This allows time to update the client to use the new shared secret.

Steps

Create a new JSON PDP API shared secret and assign it to the JSON PDP API HTTP Servlet Extension. Learn more in Creating a shared secret.
Update the client to use the new shared secret.
Remove the previous JSON PDP API shared secret. Learn more in Deleting a shared secret.

Customizing the shared secret header

By default, the JSON PDP API accepts a shared secret from a client through the CLIENT-TOKEN header.

Steps

To customize a shared secret header, change the value of the JSON PDP API HTTP Servlet Extension’s shared-secret-header property.

Example:
The following command changes the shared secret header to x-shared-secret.
{pingauthorize}/bin/dsconfig set-http-servlet-extension-prop \ --extension-name "JSON PDP API" \ --set shared-secret-header-name:x-shared-secret
The following command resets the shared secret header to its default value.
{pingauthorize}/bin/dsconfig set-http-servlet-extension-prop \ --extension-name "JSON PDP API" \ --reset shared-secret-header-name