Why does the Membrane OAuth2 token endpoint return 500 Internal Server Error?

The token endpoint of the oauth2authserver plugin threw an unexpected exception while handling a token request. Usually the client sent parameters that cannot be parsed, such as a parameter sent twice or a malformed percent-escape. Less often, creating the tokens failed.

Why does the response not contain any details?

The token endpoint always hides the details, even in development mode. The full error and the stack trace are written to the Membrane log at error level.

500 Internal Server Error: OAuth2 Token Endpoint Failure

Q: Do wrong client credentials lead to this error?

No. Missing or wrong parameters, unknown clients and wrong secrets get an OAuth2 JSON error such as invalid_request or unauthorized_client, not a 500.

Membrane API Gateway returns 500 Internal Server Error from the token endpoint of the oauth2authserver plugin when that endpoint throws an unexpected exception while it handles a token request. In most cases the client sent parameters that the endpoint cannot parse.

The Error Response

The response contains the status 500 Internal Server Error and the problem type https://membrane-api.io/problems/internal. The type internal means that the gateway could not complete the processing of the message. The endpoint always hides the details, so the title reads Internal Server Error, and the response contains neither an error message nor a link to this page, even in development mode. You find the link to this page in the gateway log.

What the Token Endpoint Does

The oauth2authserver plugin turns Membrane into an OAuth2 authorization server. Clients exchange an authorization code, a refresh token or their credentials for tokens at <basePath>/oauth2/token. Regular protocol errors do not lead to this 500: missing or wrong parameters, unknown clients and wrong secrets get an OAuth2 JSON error such as invalid_request or unauthorized_client. For the flows in general, see the authorization code flow tutorial.

Common Causes

A Parameter Is Sent Twice

The endpoint parses the query string and the form body strictly. If a parameter occurs more than once, for example grant_type twice, parsing fails with Could not parse query.

A Parameter Is Badly Encoded

A value contains a malformed percent-escape, such as %G1 or a lone %, so URL decoding fails.

The Request Cannot Be Read

The request URI cannot be parsed, or the request body cannot be read or decoded, for example because of a wrong Content-Encoding or an interrupted transfer.

Creating the Tokens Failed

Creating the access, refresh or ID token failed, for example because signing the ID token failed. The cause is a misconfigured key or token generator on the oauth2authserver, or a bug in Membrane.

How to Fix It

Client side: send each form parameter only once and percent-encode the values correctly.
Gateway operator: check the gateway log. The full stack trace is logged at error level and tells parameter errors apart from token creation errors.
For token creation errors, check the key and token generator configuration of the oauth2authserver.
If the configuration is correct, report the problem with the stack trace on GitHub Issues.

Details Only in the Log

The token endpoint always answers as if the gateway were running in production mode. Setting or removing production: true in the configuration does not change this response: the client gets neither the details nor the link to this page. Membrane writes the full error, including the stack trace, to the gateway log at error level. That log entry is the place to start.