500 Internal Server Error: Token Validation Endpoint Failed

Membrane API Gateway returns 500 Internal Server Error when the tokenValidator plugin cannot call its validation endpoint to check the client's access token. The validation endpoint or its configuration is to blame, not the token itself.

The Error Response

The response contains the status 500 Internal Server Error, the title Internal server error., the problem type https://membrane-api.io/problems/internal and a link to this page. In development mode, the exception message is included as well. The type internal means that the gateway could not complete the processing of the exchange. In production mode, the title is replaced by Internal Server Error and the details are left out.

How the Token Validator Works

The tokenValidator plugin forwards the access token of each request to the URL configured in endpoint, usually the userinfo endpoint of an authorization server. If the endpoint answers with 200, the request continues. Any other answer leads to 400 Bad Request. This error occurs when the call to the endpoint itself fails.

Common Causes

The Validation Endpoint Is Unreachable

The connection is refused, the host name cannot be resolved, or the call times out.

The TLS Handshake Fails

For an HTTPS endpoint, the gateway does not trust the endpoint's certificate, or the handshake fails for another reason.

The Endpoint URL Is Invalid

The value of endpoint is not a valid URL.

The Endpoint Closes the Connection

The validation service closed the connection without sending a response.

An Unexpected Exception in the Plugin

Any other exception that the tokenValidator plugin does not turn into an error response itself is reported under the same URL by Membrane's generic error handler. The detail then reads Aborting! Exception caused in … flow. and names the plugin, the request URI and the flow. Unless the exception points to your configuration or to the message, this usually indicates a bug in Membrane.

How to Fix It

1. Gateway operator: check the endpoint attribute of tokenValidator and that the gateway host can reach it (DNS, firewall, port).
2. Gateway operator: for HTTPS endpoints, make sure the gateway trusts the endpoint's certificate.
3. Check the health and the log of the validation service.
4. Look at the exception in the response (development mode) or in the gateway log.

The endpoint is set on the plugin:

api:
  port: 2000
  flow:
    - tokenValidator:
        endpoint: http://localhost:7007/oauth2/userinfo
  target:
    host: localhost
    port: 3000

api:
  port: 2000
  flow:
    - tokenValidator:
        endpoint: http://localhost:7007/oauth2/userinfo
  target:
    host: localhost
    port: 3000

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---. The title then reads Internal Server Error, and instead of the details the response only contains a log key. Search the gateway log for this key to find the exception.

If the plugin is nested inside a request, response or abort element and throws an unexpected exception, the exception message, the stack trace and the link to this page are currently sent even in production mode. Fix the failing plugin rather than relying on production mode to hide them.

Related Documentation

Configuration reference:

• tokenValidator

Tutorials with runnable examples:

• OAuth2 Basics
• OAuth2 Client Token Renewal

← All Membrane error messages