PingAuthorize

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

  1. 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.

  2. 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.

About this task

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

  1. Create a new JSON PDP API Shared Secret and assign it to the JSON PDP API HTTP Servlet Extension. For more information, see Creating a shared secret.

  2. Update the client to use the new shared secret.

  3. Remove the previous JSON PDP API Shared Secret. For more information, see 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