The AWS API Gateway allows to use a custom authoriser for handling AWS Lambda endpoint authentication and authorisation logic. This is useful when a third-party is used to provide authorisation or specific authorisation logic needs to be executed. Serverless allows to specify the authoriser used for each lambda endpoint. This post tries to give a quick overview of how custom lambda endpoint authorisers can be used to handle a varied range of requests when deploying with Serverless.
There are two types of authorisers supported by the API Gateway: token and request. The token authoriser expects the request to contain an authorisation header with a bearer token. If the header is not provided, the request is immediately flagged as unauthorized and the custom authorisation lambda is never called. The request authoriser receives the full request, including all the headers, and is able to execute custom logic based on the request or some other arbitrary logic.
To specify the authoriser’s type, we can simply extend the Serverless lambda HTTP event definition with authorizer property:
functions:
create:
handler: foo.handle
events:
- http:
path: foo/bar
method: post
authorizer:
arn: xxx:xxx:xxx
resultTtlInSeconds: 0
identitySource: method.request.header.Authorization
identityValidationExpression: regex
type: token
The arn field should contain the arn of the authorizer lambda deployed independently of this service. It is also possible to define the authoriser in the same service using a name field instead of arn:
functions:
create:
...
authorizer:
name: auth
...
auth:
handler: auth.handle
The resultTtlInSeconds field defines for how long the authorisation policy should be cached for. In our example, caching is disabled. The identitySource and identityValidationExpression are used by the API Gateway to filter the incoming requests. The former defines which property present in the request will be used to perfor the filterering. While the latter, describes the structure that the former must adhere to. If the specified identity source is not present or is malformed, the request will be flagged as unauthorised by the API Gateway. The indentity source is also used to cache the response policy. A list of request data properties, that can be used as indentity sources, can be found here.
In the examples above, we defined authorisation header as our indentity source. This will force all valid requests to contain this header. If we want to avoid this, we need to change the authoriser’s type to request, set TTL to zero and define the indentity source as an empty string:
authorizer:
arn: xxx:xxx:xxx
resultTtlInSeconds: 0
identitySource: ""
type: request
In this case, all requests, no matter their content, will be processed by the API Gateway and passed to the custom authoriser. We set the TTL to zero, as caching is now not possible.
More details regarding the use of custom authorisers in AWS Gateway with Serverless can be found here: