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.

Error templates include the following context parameters:

Parameter Type Description

status

Number

HTTP status code

message

String

Exception message

Example: Configuring error templates

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

Error responses that use this error template include the following fields:

  • code

  • message

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 server 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"

    Example:

    A deny policy decision results in the following response:

    HTTP/1.1 403 Forbidden
Content-Length: 57
Content-Type: application/json;charset=utf-8
Correlation-Id: e7c8fb82-f43e-4678-b7ff-ae8252411513
Date: Wed, 27 Feb 2019 05:54:50 GMT
Request-Id: 56

{
  "code": "ACCESS_FAILED",
  "message": "Access Denied"
}