Why does Membrane API Gateway return 401 with Could not retrieve JWT?

The request has no token where the jwtAuth plugin looks for it. By default, the JWT is read from the Authorization header with a Bearer prefix.

What does JWT signed by unknown key mean in Membrane?

The kid in the token header does not match any key in the jwks configuration of the jwtAuth plugin. After a key rotation at the identity provider, the new key must be available in the JWKS.

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.

401 Unauthorized: JWT Rejected

Membrane API Gateway returns 401 Unauthorized with a link to this page when the jwtAuth plugin finds no usable JWT or no matching key for it. The request is rejected in the request flow and never reaches the backend.

The Error Response

The response contains the status 401 Unauthorized, a detail that names the problem, the problem type https://membrane-api.io/problems/security and a link to this page. The type security means that a security plugin refused access to the API.

How JWT Authentication Works

The jwtAuth plugin reads the token from the request, by default from the Authorization header with the Bearer prefix. It uses the kid in the token header to pick a key from jwks, verifies the signature and checks the claims. Keys can be configured inline or loaded from jwksUris:

api:
  port: 4000
  flow:
    - jwtAuth:
        expectedAud: order
        jwks:
          jwksUris: https://login.microsoftonline.com/common/discovery/keys
  target:
    url: http://localhost:3000

api:
  port: 4000
  flow:
    - jwtAuth:
        expectedAud: order
        jwks:
          jwksUris: https://login.microsoftonline.com/common/discovery/keys
  target:
    url: http://localhost:3000

Common Causes

Could Not Retrieve JWT

The header the JWT is read from is missing. Check that the client sends Authorization: Bearer <token>. If the token comes in another header, configure a headerJwtRetriever with the right header and removeFromValue.

JWTs Compact Serialization Not Valid

The token does not consist of three parts separated by dots. It may be truncated, or the client sent an opaque access token instead of a JWT.

JWT Header Is Not Valid JSON

The header or payload part of the token does not decode to a JSON object.

JWT Does Not Contain Kid

The token's header has no kid. The key ID is required to choose the verification key.

JWT Signed by Unknown Key

No key in jwks has the token's kid. The token comes from a different identity provider, or the provider rotated its keys and the new key is not in the configured JWKS.

Other errors while reading the token are reported under retrieving-jwt, and tokens that fail verification under jwt-validation-failed.

How to Fix It

Client: send a complete, well-formed JWT as Authorization: Bearer <token>, issued by the expected identity provider.
Operator: check that jwks, inline or via jwksUris, contains the provider's current signing keys, including the kid the tokens use.
Operator: if the token is sent in another header, configure a headerJwtRetriever.

See the JWT tutorial for a complete example.

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