PingAuthorize

Gateway 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 Gateway-generated error:

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

  • An internal error occurs in the gateway, or when the gateway cannot contact the API service. These scenarios typically result in 500, 502, or 504 errors.

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 Gateway API Endpoint produces error responses.

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

Error templates include the following context parameters:

Parameter Type Description

status

Number

HTTP status code

message

String

Exception message

requestURI

String

Original Request URI

requestQueryParams

Object

Query parameters as JSON object

headers

Object

Request headers as JSON object

correlationID

String

Request correlation ID

Example: Configuring error templates

This example demonstrates the configuration of a custom error template for a Gateway 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 Gateway API Endpoint:

    dsconfig set-gateway-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"
}