Customize 401 Unauthorized response from AWS Lambda Authorizer

Question

I am developing an API with AWS API Gateway, and the authorization to consume the API endpoints is based on JWT tokens. As a requirement, the server needs to follow strictly the behavior described in RFC 6750: "OAuth 2.0 Bearer Token Usage".

In particular, the server must send back the following HTTP error codes, and HTTP headers:

1. If the HTTP request does not contain a JWT token:

   • Response: 401 Unauthorized, with WWW-Authenticate set to Bearer realm="example"

2. If the HTTP request contains an invalid JWT token:

   • Response: 401 Unauthorized, with WWW-Authenticate set to Bearer realm="example" error="invalid_token"

3. If the HTTP request contains a valid JWT token, but a required scope is not present inside the token claims:

   • Response: 403 Forbidden, with WWW-Authenticate set to Bearer realm="example" error="insufficient_scope"

I have tried to achieve this behavior with Lambda authorizers, but I fail to see how can I customize the content of the WWW-Authenticate header.

I am aware that it is possible to use the "Gateway responses" feature, in the API Gateway, to set the WWW-Authenticate header to a certain fixed value (e.g. Bearer realm="example"), but I fail to see how to set the error parameter in the header, for the different failure conditions (invalid token, insufficient scope, etc...).

Any clue on how to achieve this?

Inside the Lambda authorizer, as it seems, the only option to trigger the 401 response is (using node.js):

callback("Unauthorized");

but this does not allow to set the different parameters of the WWW-Authenticate header (realm, error, etc..)

Then, using "Gateway responses" in the API Gateway, the only option seems to be to set a fixed value for the WWW-Authenticate header, but I need to set different parameters ("error") depending on the error condition of the JWT token in the request, as indicated in RFC 6750, section 3.