Error handling

If the custom logic webhook returns an error, Gatekeeper attempts to call again the webhook with the exact same request, as long as the total number of attempts is less than maxAttempts. By default, Gatekeeper gives up after 5 total attempts. If maxAttempts is set to 1, Gatekeeper won’t reattempt to call the webhook if it received an error.

When Gatekeeper fails to receive a successful result from the custom logic webhook and WebhookAbortFlowOnError is set to false, the selected flow in FlowName continues as if the webhook wasn’t configured. Gatekeeper reattempts to reach the webhook at the next event.

If WebhookAbortFlowOnError is set to true, a REPORT_ERROR_ACTION error is displayed to the agent, and the current call’s flow stops. Also, no other event in that call is sent to the webhook. Use this during development, or if you consider the built-in flow selected in FlowName to not be usable in your environment if a single (unfiltered) event is missed.

The following is a non-exhaustive list of those errors:

• The host name specified in host can’t be resolved to an IP address.

• The host can’t be reached from where Gatekeeper resides.

• A TCP connection can’t be established.

• The TLS handshake produced an error. Possible reasons include:

  • Invalid server certificate, either using the common root certificate authorities, or against what was provided in trustedCACerts.
  • The webhook rejected the client’s certificate.
  • The webhook doesn’t support TLS v1.2, or a supported set of secure cryptographic algorithms.

• The TCP connection disconnects.

  Note:

  The gRPC and REST clients try to re-establish the connection automatically, but give up when they can’t do so before timeoutMs or callStartTimeoutMs.

• The response wasn’t received before timeoutMs or callStartTimeoutMs.

• The HTTP status code is something other than 200.

  • There is only limited support for some other codes, such as 100 Continue. Redirection codes (3xx) aren’t currently supported.

• gRPC:

  • The response isn’t a valid or expected Protobuf message.
  • The webhook doesn’t implement the gRPC service nuance.biosec.v1.CustomBusinessLogic.

• REST:

  • The response’s content-type header isn’t set to the application/json type.
  • The response’s encoding isn’t UTF-8.
  • The response is an invalid JSON structure.
  • The response doesn’t validate against the “Custom Logic Webhook API” OpenAPI JSON Schema.

• The value of responseCode in the response has any value other than 200 or is missing.

Sample flows

Here are a few diagrams that illustrate the flows.

Main flow diagram

Enrollment flow diagram

Verification flow diagram