Configure an API Gateway Lambda authorizer - Amazon API Gateway

Configure an API Gateway Lambda authorizer

After you create a Lambda function, you configure the Lambda function as an authorizer for your API. You then configure your method to invoke your Lambda authorizer to determine if a caller can invoke your method. You can create a Lambda function in the same account, or a different account, from where you created your API.

You can test your Lambda authorizer using built-in tools in the API Gateway console or by using Postman. For instructions for how to use Postman to test your Lambda authorizer function, see Call an API with an API Gateway Lambda authorizer.

Configure a Lambda authorizer (console)

The following procedure shows how to create a Lambda authorizer in the API Gateway REST API console. To learn more about the different types of Lambda authorizers, see Choosing a type of Lambda authorizer.

REQUEST authorizer
To configure a REQUEST Lambda authorizer
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Select an API, and then choose Authorizers.

  3. Choose Create authorizer.

  4. For Authorizer name, enter a name for the authorizer.

  5. For Authorizer type, select Lambda.

  6. For Lambda function, select the AWS Region where you created your Lambda authorizer function, and then enter the function name.

  7. Keep Lambda invoke role blank to let the API Gateway REST API console set a resource-based policy. The policy grants API Gateway permissions to invoke the Lambda authorizer function. You can also choose to enter the name of an IAM role to allow API Gateway to invoke the Lambda authorizer function. For an example role, see Create an assumable IAM role.

  8. For Lambda event payload, select Request.

  9. For Identity source type, select a parameter type. Supported parameter types are Header, Query string, Stage variable, and Context. To add more identity sources, choose Add parameter.

  10. To cache the authorization policy generated by the authorizer, keep Authorization caching turned on. When policy caching is enabled, you can modify the TTL value. Setting the TTL to zero disables policy caching.

    If you enable caching, your authorizer must return a policy that is applicable to all methods across an API. To enforce a method-specific policy, use the context variables $context.path and $context.httpMethod.

  11. Choose Create authorizer.

TOKEN authorizer
To configure a TOKEN Lambda authorizer
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Select an API, and then choose Authorizers.

  3. Choose Create authorizer.

  4. For Authorizer name, enter a name for the authorizer.

  5. For Authorizer type, select Lambda.

  6. For Lambda function, select the AWS Region where you created your Lambda authorizer function, and then enter the function name.

  7. Keep Lambda invoke role blank to let the API Gateway REST API console set a resource-based policy. The policy grants API Gateway permissions to invoke the Lambda authorizer function. You can also choose to enter the name of an IAM role to allow API Gateway to invoke the Lambda authorizer function. For an example role, see Create an assumable IAM role.

  8. For Lambda event payload, select Token.

  9. For Token source, enter the header name that contains the authorization token. The caller must include a header of this name to send the authorization token to the Lambda authorizer.

  10. (Optional) For Token validation, enter a RegEx statement. API Gateway performs initial validation of the input token against this expression and invokes the authorizer upon successful validation.

  11. To cache the authorization policy generated by the authorizer, keep Authorization caching turned on. When policy caching is enabled, the header name specified in Token source becomes the cache key. When policy caching is enabled, you can modify the TTL value. Setting the TTL to zero disables policy caching.

    If you enable caching, your authorizer must return a policy that is applicable to all methods across an API. To enforce a method-specific policy, you can turn off Authorization caching.

  12. Choose Create authorizer.

After your create your Lambda authorizer, you can test it. The following procedure shows how to test your Lambda authorizer.

REQUEST authorizer
To test a REQUEST Lambda authorizer
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Select the name of your authorizer.

  3. Under Test authorizer, enter a value for your identity source.

    If you are using the Example REQUEST authorizer Lambda function, do the following:

    1. Select Header and enter headerValue1, and then choose Add parameter.

    2. Under Identity source type, select Query string and enter queryValue1, and then choose Add parameter.

    3. Under Identity source type, select Stage variable and enter stageValue1.

    You can't modify the context variables for the test invocation, but you can modify the API Gateway Authorizer test event template for your Lambda function. Then, you can test your Lambda authorizer function with modified context variables. For more information, see Testing Lambda functions in the console in the AWS Lambda Developer Guide.

  4. Choose Test authorizer.

TOKEN authorizer
To test a TOKEN Lambda authorizer
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Select the name of your authorizer.

  3. Under Test authorizer, enter a value for your token.

    If you are using the Example TOKEN authorizer Lambda function, do the following:

    1. For the authorizationToken, enter allow.

  4. Choose Test authorizer.

    If your Lambda authorizer successfully denies a request in the test environment, the test responds with a 200 OK HTTP response. However, outside of the test environment, API Gateway returns a 403 Forbidden HTTP response and the method request fails.

Configure a Lambda authorizer (AWS CLI)

The following create-authorizer command shows to create a Lambda authorizer using the AWS CLI.

REQUEST authorizer

The following example creates a REQUEST authorizer and uses the Authorizer header and accountId context variable as identity sources:

aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Request_Custom_Authorizer' \ --type REQUEST \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization,context.accountId' \ --authorizer-result-ttl-in-seconds 300
TOKEN authorizer

The following example creates a TOKEN authorizer and uses the Authorization header as the identity source:

aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Token_Custom_Authorizer' \ --type TOKEN \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization' \ --authorizer-result-ttl-in-seconds 300

After your create your Lambda authorizer, you can test it. The following test-invoke-authorizer command shows how to test your Lambda authorizer:

aws apigateway test-invoke-authorizer --rest-api-id 1234123412 \ --authorizer-id efg1234 \ --headers Authorization='Value'

Configure a method to use a Lambda authorizer (console)

After you configure your Lambda authorizer, you must attach it to a method for your API.

To configure an API method to use a Lambda authorizer
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Select an API.

  3. Choose Resources, and then choose a new method or choose an existing method.

  4. On the Method request tab, under Method request settings, choose Edit.

  5. For Authorizer, from the dropdown menu, select the Lambda authorizer you just created.

  6. (Optional) If you want to pass the authorization token to the backend, choose HTTP request headers. Choose Add header, and then add the name of the authorization header. For Name, enter the header name that matches the Token source name you specified when you created the Lambda authorizer for the API. This step does not apply to REQUEST authorizers.

  7. Choose Save.

  8. Choose Deploy API to deploy the API to a stage. For a REQUEST authorizer using stage variables, you must also define the required stage variables and specify their values while on the Stages page.

Configure a method to use a Lambda authorizer (AWS CLI)

After you configure your Lambda authorizer, you must attach it to a method for your API. You can create a new method or use a patch operation to attach an authorizer to an existing method.

The following put-method command shows how to create a new method that uses an Lambda authorizer:

aws apigateway put-method --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --authorization-type CUSTOM \ --authorizer-id efg1234

The following update-method command shows how to update an existing method to use a Lambda authorizer:

aws apigateway update-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --patch-operations op="replace",path="/authorizationType",value="CUSTOM" op="replace",path="/authorizerId",value="efg1234"