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 feature 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

Configuring error templates example

The example in this section demonstrates the configuration of a custom error template for a Gateway API Endpoint named Test API.

About this task

Error responses that use this error template feature 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 configuration, as follows:

    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, as follows:

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

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

    Example:

    A policy deny results in a response like the following example:

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