PingAuthorize

Sideband error templates

REST API clients often expect a custom error format that the API produces. Some clients might fail unexpectedly if they encounter an error response that uses an unexpected format.

When PingAuthorize Server proxies an API, errors returned by the API are forwarded to the client as-is, unless a policy dictates a modification of the response. In the following scenarios, PingAuthorize Server returns a Sideband API-generated error:

  • The policy evaluation results in a deny response. This typically results in a 403 error.

  • An internal error occurs in the Sideband API. This typically results in a 500 error.

By default, these responses use a simple error format:

{
  "errorMessage": "Access Denied",
  "status": 403
}

The following table describes the default error format:

Field Type Description

errorMessage

String

Error message

status

Number

HTTP status code

Because some API clients expect a specific error-response format, PingAuthorize Server provides error templates to respond with custom errors. Error templates, which are written in Velocity Template Language, define how a Sideband API Endpoint produces error responses.

Sideband API error templates don’t support forwarding the WWW-Authenticate header to the client. If your policies use the auth-challenge statement to challenge clients for step-up authentication, don’t use error templates.

The following table identifies the context parameters that are provided with error templates:

Parameter Type Description

status

Number

HTTP status code

message

String

Exception message

Example: Configure error templates

This example demonstrates the configuration of a custom error template for a Sideband API Endpoint called Test API.

The following fields are associated with the error responses that use this error template:

  • code

  • message

To create the error template, perform the following steps:

  1. Create a file named error-template.vtl with the following contents:

    #set ($code = "UNEXPECTED_ERROR")
#if($status == 403)
  #set ($code = "ACCESS_FAILED")
#end
{
  "code":"$code",
  "message":"$message"
}

  2. Add the error template to the configuration.

    dsconfig create-error-template \
  --template-name "Custom Error Template" \
  --set "velocity-template<error-template.vtl"

  3. Assign the error template to the Sideband API Endpoint.

    dsconfig set-sideband-api-endpoint-prop \
  --endpoint-name "Test API" \
  --set "error-template:Custom Error Template"

The error template is used whenever the Sideband API generates an error in response to a request.