Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
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.
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
-
Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.
-
Select an API, and then choose Authorizers.
-
Choose Create authorizer.
-
For Authorizer name, enter a name for the authorizer.
-
For Authorizer type, select Lambda.
-
For Lambda function, select the Amazon Web Services Region where you created your Lambda authorizer
function, and then enter the function name.
-
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.
-
For Lambda event payload, select Request.
-
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.
-
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.
-
Choose Create authorizer.
- TOKEN authorizer
To configure a TOKEN Lambda authorizer
-
Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.
-
Select an API, and then choose Authorizers.
-
Choose Create authorizer.
-
For Authorizer name, enter a name for the authorizer.
-
For Authorizer type, select Lambda.
-
For Lambda function, select the Amazon Web Services Region where you created your Lambda authorizer
function, and then enter the function name.
-
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.
-
For Lambda event payload, select Token.
-
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.
-
(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.
-
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.
-
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
-
Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.
-
Select the name of your authorizer.
-
Under Test authorizer, enter a value for your identity source.
If you are using the Example REQUEST authorizer Lambda function, do the following:
-
Select Header and enter
headerValue1, and then choose Add parameter.
-
Under Identity source type, select Query string
and enter
queryValue1, and then choose Add parameter.
-
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
Amazon Lambda Developer Guide.
-
Choose Test authorizer.
- TOKEN authorizer
To test a TOKEN Lambda authorizer
-
Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.
-
Select the name of your authorizer.
-
Under Test authorizer, enter a value for your token.
If you are using the Example TOKEN authorizer
Lambda function, do the following:
For the authorizationToken, enter allow.
-
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.
The following create-authorizer
command shows to create a Lambda authorizer using the Amazon 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'
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
-
Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.
-
Select an API.
-
Choose Resources, and then choose a new method or choose an existing method.
-
On the Method request tab, under Method request settings, choose Edit.
-
For Authorizer, from the dropdown menu, select the Lambda authorizer you just created.
-
(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.
-
Choose Save.
-
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.
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"