PingAuthorize

Authenticating to the Sideband API

The Sideband API can require an API gateway plugin to authenticate to it by using a shared secret.

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

Creating a shared secret

Define the authentication credentials that the Sideband API might require an API gateway plugin 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-sideband-api-shared-secret \
  --secret-name "Shared Secret A" \
  --set "shared-secret:secret123"

    • The shared-secret property sets the value that the Sideband API requires the API gateway plugin 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 Sideband 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 "Sideband API" \
  --add "shared-secrets:Shared Secret A"

    A new Sideband API Shared Secret is not used until the shared-secrets property of the Sideband 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 Sideband 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 "Sideband API" \
  --remove "shared-secrets:Shared Secret A"

  • To delete a Sideband API Shared Secret, run the following example dsconfig command.

    Example:

    {pingauthorize}/bin/dsconfig delete-sideband-api-shared-secret \
  --secret-name "Shared Secret A"

Rotating shared secrets

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

You can configure a new shared secret that the Sideband API accepts alongside an existing shared secret. This allows time to update the API gateway plugin to use the new shared secret.

Steps

  1. Create a new Sideband API Shared Secret and assign it to the Sideband API HTTP Servlet Extension. Learn more in Creating a shared secret.

  2. Update the API gateway plugin to use the new shared secret.

  3. Remove the previous Sideband API Shared Secret. Learn more in Deleting a shared secret.

Customizing the shared secret header

By default, the Sideband API accepts a shared secret from an API gateway plugin through the CLIENT-TOKEN header.

Steps

  • To customize a shared secret header, change the value of the Sideband 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 "Sideband 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 "Sideband API" \
  --reset shared-secret-header-name