Configure a Lambda authorizer using the API Gateway console

After you create the Lambda function and verify that it works, use the following steps to configure the API Gateway Lambda authorizer (formerly known as the custom authorizer) in the API Gateway console.

Old REST API console

Note

We've redesigned the API Gateway console. On 30th October 2023, the old console will no longer be available.

To configure a Lambda authorizer using the API Gateway console

1. Sign in to the API Gateway console.

2. Create a new or select an existing API and choose Authorizers under that API.

3. Choose Create New Authorizer.

4. For Create Authorizer, type an authorizer name in the Name input field.

5. For Type, choose the Lambda option.

6. For Lambda Function, choose a region and then choose an available Lambda authorizer function that's in your account.

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

   If you choose to let the API Gateway console set the resource-based policy, the Add Permission to Lambda Function dialog is displayed. Choose OK. After the Lambda authorization is created, you can test it with appropriate authorization token values to verify that it works as expected.

8. For Lambda Event Payload, choose either Token for a TOKEN authorizer or Request for a REQUEST authorizer. (This is the same as setting the type property to TOKEN or REQUEST.)

9. Depending on the choice of the previous step, do one of the following:

   1. For the Token options, do the following:

      • Type the name of a header in Token Source. The API client must include a header of this name to send the authorization token to the Lambda authorizer.

      • Optionally, provide a RegEx statement in Token Validation input field. API Gateway performs initial validation of the input token against this expression and invokes the authorizer upon successful validation. This helps reduce chances of being charged for invalid tokens.

      • For Authorization Caching, select or clear the Enabled option, depending on whether you want to cache the authorization policy generated by the authorizer or not. When policy caching is enabled, you can choose to modify the TTL value. Setting TTL to zero disables policy caching. When policy caching is enabled, the header name specified in Token Source becomes the cache key. If multiple values are passed to this header in the request, all values will become the cache key, with the order preserved.

        Note

        The default TTL value is 300 seconds. The maximum value is 3600 seconds; this limit cannot be increased.

   2. For the Request option, do the following:

      • For Identity Sources, type a request parameter name of a chosen parameter type. Supported parameter types are Header, Query String, Stage Variable, and Context. To add more identity sources, choose Add Identity Source.

        API Gateway uses the specified identity sources as the request authorizer caching key. When caching is enabled, API Gateway calls the authorizer's Lambda function only after successfully verifying that all the specified identity sources are present at runtime. If a specified identify source is missing, null, or empty, API Gateway returns a 401 Unauthorized response without calling the authorizer Lambda function.

        When multiple identity sources are defined, they are all used to derive the authorizer's cache key. Changing any of the cache key parts causes the authorizer to discard the cached policy document and generate a new one. If a header with multiple values is passed in the request, then all values will be part of the cache key, with the order preserved.

      • For Authorization Caching, select or deselect the Enabled option, depending on whether you want to cache the authorization policy generated by the authorizer or not. When policy caching is enabled, you can choose to modify the TTL value from the default (300). Setting TTL=0 disables policy caching.

        When caching is disabled, it is not necessary to specify an identity source.

   Note

   To enable caching, your authorizer must return a policy that is applicable to all methods across an API. To enforce method-specific policy, you can set the TTL value to zero to disable policy caching for the API.

10. Choose Create to create the new Lambda authorizer for the chosen API.

11. After the authorizer is created for the API, you can optionally test invoking the authorizer before it is configured on a method.

    For the TOKEN authorizer, type a valid token in the Identity token input text field and the choose Test. The token will be passed to the Lambda function as the header you specified in the Identity token source setting of the authorizer.

    For the REQUEST authorizer, type the valid request parameters corresponding to the specified identity sources and then choose Test.

    In addition to using the API Gateway console, you can use AWS CLI or an AWS SDK for API Gateway to test invoking an authorizer. To do so using the AWS CLI, see test-invoke-authorizer.

    Note

    Test-invoke for method executions test-invoke for authorizers are independent processes.

    To test invoking a method using the API Gateway console, see Use the console to test a REST API method. To test invoking a method using the AWS CLI, see test-invoke-method.

    To test invoking a method and a configured authorizer, deploy the API, and then use cURL or Postman to call the method, providing the required token or request parameters.

New REST API console

To configure a Lambda authorizer using the API Gateway console

1. Sign in to the API Gateway console.

2. Create a new or select an existing 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 console set a resource-based policy. The policy grants API Gateway permissions to invoke the authorizer Lambda function. You can also choose to enter the name of an IAM role to allow API Gateway to invoke the authorizer Lambda function. For an example of such a role, see Create an assumable IAM role.

8. For Lambda event payload, select either Token for a TOKEN authorizer or Request for a REQUEST authorizer. (This is the same as setting the type property to TOKEN or REQUEST.)

9. Depending on the choice of the previous step, do one of the following:

   1. For the Token option, do the following:

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

      • Optionally, 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. This helps reduce calls to your API.

      • To cache the authorization policy generated by the authorizer, keep Authorization caching turned on. When policy caching is enabled, you can choose to modify the TTL value. Setting the TTL to zero disables policy caching. When policy caching is enabled, the header name specified in Token source becomes the cache key. If multiple values are passed to this header in the request, all values will become the cache key, with the order preserved.

        Note

        The default TTL value is 300 seconds. The maximum value is 3600 seconds; this limit cannot be increased.

   2. For the Request option, do the following:

      • 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 choose to modify the TTL value. Setting the TTL to zero disables policy caching.

        API Gateway uses the specified identity sources as the request authorizer caching key. When caching is enabled, API Gateway calls the authorizer's Lambda function only after successfully verifying that all the specified identity sources are present at runtime. If a specified identify source is missing, null, or empty, API Gateway returns a 401 Unauthorized response without calling the authorizer Lambda function.

        When multiple identity sources are defined, they are all used to derive the authorizer's cache key. Changing any of the cache key parts causes the authorizer to discard the cached policy document and generate a new one. If a header with multiple values is passed in the request, then all values will be part of the cache key, with the order preserved.

      • When caching is turned off, it is not necessary to specify an identity source.

   Note

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

10. Choose Create authorizer.

11. After the authorizer is created for the API, you can test the authorizer before it is configured on a method. To test an authorizer, select the name of the authorizer.

12. 1. For the TOKEN authorizer, under Token value, enter a valid token. Choose Test authorizer. The token will be passed to the Lambda function as the header you specified in the Token source setting of the authorizer.

    2. For the REQUEST authorizer, under Identity source type, select a parameter type and enter a value. To add more parameters, select Add parameter. Choose Test authorizer.

    In addition to using the API Gateway console, you can use AWS CLI or an AWS SDK for API Gateway to test invoking an authorizer. To do so using the AWS CLI, see test-invoke-authorizer.

    Note

    Test-invoke for method executions test-invoke for authorizers are independent processes.

    To test invoking a method using the API Gateway console, see Use the console to test a REST API method. To test invoking a method using the AWS CLI, see test-invoke-method.

    To test invoking a method and a configured authorizer, deploy the API, and then use cURL or Postman to call the method, providing the required token or request parameters.

The next procedure shows how to configure an API method to use the Lambda authorizer.

Old REST API console

Note

We've redesigned the API Gateway console. On 30th October 2023, the old console will no longer be available.

To configure an API method to use a Lambda authorizer

1. Go back to the API. Create a new method or choose an existing method. If necessary, create a new resource.

2. In Method Execution, choose the Method Request link.

3. Under Settings, expand the Authorization drop-down list to select the Lambda authorizer you just created (for example, myTestApiAuthorizer), and then choose the check mark icon to save the choice.

4. Optionally, while still on the Method Request page, choose Add header if you also want to pass the authorization token to the backend. In Name, type a header name that matches the Token Source name you specified when you created the Lambda authorizer for the API. Then, choose the check mark icon to save the settings. This step does not apply to REQUEST authorizers.

5. Choose Deploy API to deploy the API to a stage. Note the Invoke URL value. You need it when calling the API. For a REQUEST authorizer using stage variables, you must also define the required stage variables and specify their values while in Stage Editor.

New REST API console

To configure an API method to use a Lambda authorizer

1. Choose Resources. Choose a new method or choose an existing method. If necessary, create a new resource.

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

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

4. (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. In 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.

5. Choose Save.

6. Choose Deploy API to deploy the API to a stage. Note the Invoke URL value. You need it when calling the API. For a REQUEST authorizer using stage variables, you must also define the required stage variables and specify their values while on the Stages page.