Why does Membrane API Gateway return 502 Could not obtain an OAuth2 access token?

The oauth2Client plugin could not get an access token from the authorization server using the client credentials flow. Without a token, it cannot add the Authorization header, so the request is aborted before it reaches the backend.

How do I fix the OAuth2 token error in Membrane?

Check the gateway log for the reason, then verify tokenUrl, clientId, clientSecret and scope against the authorization server, for example by requesting a token with curl using the same credentials.

How do I hide the details in Membrane error responses?

Enable production mode by adding a configuration document with production: true to your apis.yaml. Membrane then leaves out detailed information from error responses.

502 Bad Gateway: Could Not Obtain an OAuth2 Access Token

Membrane API Gateway returns 502 Bad Gateway with the detail Could not obtain an OAuth2 access token. when the oauth2Client plugin cannot get an access token from the authorization server. The request is aborted before it reaches the backend. The client is not at fault.

The Error Response

The response contains the status 502 Bad Gateway, the title Bad Gateway, the detail Could not obtain an OAuth2 access token., the problem type https://membrane-api.io/problems/gateway and a link to this page. The type gateway means that the problem lies between Membrane and an upstream system, not in the client's request.

What the oauth2Client Plugin Does

The oauth2Client plugin fetches an access token from the tokenUrl using the client credentials flow and adds it to the request as an Authorization: Bearer header. A token is cached until it expires, when the authorization server sends expires_in.

api:
  port: 2000
  flow:
    - oauth2Client:
        tokenUrl: https://auth.example.com/oauth2/token
        clientId: gateway
        clientSecret: secret
        scope: orders
  target:
    url: https://api.example.com

api:
  port: 2000
  flow:
    - oauth2Client:
        tokenUrl: https://auth.example.com/oauth2/token
        clientId: gateway
        clientSecret: secret
        scope: orders
  target:
    url: https://api.example.com

Common Causes

The Token Endpoint Rejects the Request

The token endpoint answers with a status other than 200, for example 401 because clientId or clientSecret is wrong, or 400 because the requested scope is not allowed for this client.

The Token Response Is Invalid

The response of the token endpoint is not JSON, has no access_token field, or the field is empty.

The Authorization Server Cannot Be Reached

The host is unknown, the connection is refused, or the request times out or fails in the TLS handshake. The token request uses the global HTTP client configuration of the gateway (configuration.httpClientConfig), including its proxy settings.

The tokenUrl Points to the Wrong Endpoint

A common mistake is to configure the authorization endpoint instead of the token endpoint.

How to Fix It

Check the gateway log. Membrane logs Could not obtain OAuth2 access token from ... at info level with the reason, and the full exception at debug level.
Request a token with curl using the same tokenUrl, clientId, clientSecret and scope to see the answer of the authorization server.
If the authorization server is only reachable through a proxy, configure it under configuration.httpClientConfig.proxy.

Clients can retry the request once the problem is fixed.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem, including the link to this page. 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 ---.

In production mode, the title of this error is replaced by Internal Server Error, and the response only says Internal details are hidden. See server log (key: ...). Search the gateway log for that key to find the full error message.