Use Amazon API Gateway Custom Authorizers

An Amazon API Gateway custom authorizer is a Lambda function that you provide to control access to your APIs using bearer token authentication strategies, such as OAuth or SAML.

When a client calls your API, API Gateway verifies whether a custom authorizer is configured for the API. If so, API Gateway calls the Lambda function, supplying the authorization token extracted from a specified request header. You use this Lambda function to implement various authorization strategies, such as JSON Web Token (JWT) verification and OAuth provider callout, to return IAM policies that authorize the request. If the returned policy is invalid or the permissions are denied, the API call will not succeed. For a valid policy, API Gateway caches the returned policy, associated with the incoming token and used for the current and subsequent requests, over a pre-configured time-to-live (TTL) period of up to 3600 seconds. You can set the TTL period to zero seconds to disable the policy caching. The default TTL value is 300 seconds. Currently, the maximum TTL value of 3600 seconds cannot be increased.

Before creating an API Gateway custom authorizer, you must first create the AWS Lambda function that implements the logic to authenticate and authorize the caller. You can do so in the Lambda console, using the code template available from the API Gateway Custom Authorizer blueprint. Or you can create one from scratch. For illustration purposes, we will explain here the creation of the Lambda function without using the blueprint.

When creating the Lambda function for your API Gateway custom authorizer, you will be asked to assign an execution role for the Lambda function if it calls other AWS services. For the following example, the basic AWSLambdaRole will suffice. For more involved use cases, follow the instructions to grant permissions in an execution role for the Lambda function.

In the code editor of the Lambda console, enter the following Node.js code.

console.log('Loading function');

exports.handler =  (event, context, callback) => {
    var token = event.authorizationToken;
    // Call oauth provider, crack jwt token, etc.
    // In this example, the token is treated as the status for simplicity.

    switch (token.toLowerCase()) {
        case 'allow':
            callback(null, generatePolicy('user', 'Allow', event.methodArn));
            break;
        case 'deny':
            callback(null, generatePolicy('user', 'Deny', event.methodArn));
            break;
        case 'unauthorized':
            callback("Unauthorized");   // Return a 401 Unauthorized response
            break;
        default:
            callback("Error: Invalid token"); 
    }
};

var generatePolicy = function(principalId, effect, resource) {
    var authResponse = {};
    
    authResponse.principalId = principalId;
    if (effect && resource) {
        var policyDocument = {};
        policyDocument.Version = '2012-10-17'; // default version
        policyDocument.Statement = [];
        var statementOne = {};
        statementOne.Action = 'execute-api:Invoke'; // default action
        statementOne.Effect = effect;
        statementOne.Resource = resource;
        policyDocument.Statement[0] = statementOne;
        authResponse.policyDocument = policyDocument;
    }
    
    // Can optionally return a context object of your choosing.
    authResponse.context = {};
    authResponse.context.stringKey = "stringval";
    authResponse.context.numberKey = 123;
    authResponse.context.booleanKey = true;
    return authResponse;
}

The preceding Lambda function returns an Allow IAM policy on a specified method if the request's authorization token contains an 'allow' value, thereby permitting a caller to invoke the specified method. The caller receives an 200 OK response. The function returns a Deny policy against the specified method if the authorization token has a 'deny' value, thus blocking the caller from calling the method. The client will receive a 403 Forbidden response. If the token is 'unauthorized', the client will receive a 401 Unauthorized response. If the token is 'fail' or anything else, the client will receive a 500 Internal Server Error response. In both of the last two cases, the calls will not succeed.

Besides returning an IAM policy in a custom authorizer, the Lambda function must also return the caller's principal identifier and can optionally return a key-value map named context to contain additional information. For more information, see Output from an Amazon API Gateway Custom Authorizer.

You can then configure the integration request to pass returned context map entries to the back end. When the context map entries refer to cached credentials, the back-end service can provide better latency and, hence, improved custom experience by leveraging the cached credentials to reduce the need to access the secret keys and open the authorization tokens for every request.

For the Lambda proxy integration, the context object returned from an custom authorizer is passed to the back-end Lambda function as the input event. You can retrieve the context key-value pairs in the Lambda function by calling <codeL>$event.requestContext.authorizer.key</codeL>. For the preceding custom authorizer example, key can be stringKey, numberKey or booleanKey.

Before going further, you may want to test the Lambda function from within the Lambda Console. To do this, configure the sample event to provide the input and verify the result by examining the output. The next two sections explain the Input to a Custom Authorizer and Output from an Amazon API Gateway Custom Authorizer.

When a custom authorizer is enabled on an API method, you must specify a custom header for the method caller to pass the required authorization token in the initial client request. Upon receiving the request, API Gateway extracts the token from the custom header as the input authorizationToken parameter value into the Lambda function and calls the custom authorizer with the following request payload.

{
    "type":"TOKEN",
    "authorizationToken":"<caller-supplied-token>",
    "methodArn":"arn:aws:execute-api:<regionId>:<accountId>:<apiId>/<stage>/<method>/<resourcePath>"
}            
        

In this example, the type property specifies the payload type. Currently, the only valid value is the TOKEN literal. The <caller-supplied-token> originates from the custom authorization header in a client request. The methodArn is the ARN of the incoming method request and is populated by API Gateway in accordance with the custom authorizer configuration.

For the custom authorizer shown in the preceeding section, the <caller-supplied-token> string is allow, deny, unauthorized, or any other string value. An empty string value is the same as unauthorized. The following shows an example of such an input to obtain an Allow policy on the GET method of an API (ymy8tbxw7b) of the AWS account (123456789012) in any stage (*).

{
    "type":"TOKEN",
    "authorizationToken":"allow",
    "methodArn":"arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/*/GET/"
}            
        

The custom authorizer's Lambda function returns an output that must include the principal identifier (principalId) and a policy document (policyDocument) containing a list of policy statements. The output can also include a context map containing key-value pairs. The following shows an example of this output.

{
  "principalId": "yyyyyyyy", // The principal user identification associated with the token sent by the client.
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": "execute-api:Invoke",
        "Effect": "Allow|Deny",
        "Resource": "arn:aws:execute-api:<regionId>:<accountId>:<appId>/<stage>/<httpVerb>/[<resource>/<httpVerb>/[...]]"
      }
    ]
  },
  "context": {
    "key": "value",
    "numKey": 1,
    "boolKey": true
  }
}
        

Here, a policy statement stipulates whether to allow or deny (Effect) the API Gateway execution service to invoke (Action) the specified API method (Resource). You can use a wild card (*) to specify a resource type (method). For information about setting valid policies for calling an API, see Statement Reference of IAM Policies for Executing API in API Gateway.

You can access the principalId value in a mapping template using the $context.authorizer.principalId variable. This is useful if you want to pass the value to the back end. For more information, see Accessing the $context Variable.

You can access the key, numKey, or boolKey value (i.e., value, 1, or true) of the context map in a mapping template by calling $context.authorizer.key, $context.authorizer.numKey, or $context.authorizer.boolKey, respectively. Notice that a JSON object or array is not a valid value of any key in the context map.

The following shows example output from the example custom authorizer. The example output contains a policy statement to block (Deny) calls to the GET method in an API (ymy8tbxw7b) of an AWS account (123456789012) in any stage (*).

{
  "principalId": "user",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": "execute-api:Invoke",
        "Effect": "Deny",
        "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/*/GET/"
      }
    ]
  }
}
        

After you create the Lambda function and verify that it works, you can configure the API Gateway Custom Authorizer in the API Gateway console.

This completes the procedure to create a custom authorization. The next procedure shows how to configure an API method to use the custom authorizer.

After you configure your API to use the custom authorizer, you or your customers can call the API using the custom authorizer. Because it involves submitting a custom authorization token header in the requests, you need a REST client that supports this. In the following examples, API calls are made using the Postman Chrome App.