Configure a cross-account Lambda authorizer

You can now also use an AWS Lambda function from a different AWS account as your API authorizer function. Each account can be in any region where Amazon API Gateway is available. The Lambda authorizer function can use bearer token authentication strategies such as OAuth or SAML. This makes it easy to centrally manage and share a central Lambda authorizer function across multiple API Gateway APIs.

In this section, we show how to configure a cross-account Lambda authorizer function using the Amazon API Gateway console.

These instructions assume that you already have an API Gateway API in one AWS account and a Lambda authorizer function in another account.

Configure a cross-account Lambda authorizer using the API Gateway console

Log in to the Amazon API Gateway console in the account that has your API in it, and then do the following:

1. Choose your API, and then in the main navigation pane, choose Authorizers.

2. Choose Create authorizer.

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

4. For Authorizer type, select Lambda.

5. For Lambda Function, enter the full ARN for the Lambda authorizer function that you have in your second account.

   Note

   In the Lambda console, you can find the ARN for your function in the upper right corner of the console window.

6. A warning with an aws lambda add-permission command string will appear. This policy grants API Gateway permission to invoke the authorizer Lambda function. Copy the command and save it for later. You run the command after you create the authorizer.

7. Keep Lambda invoke role blank to let the API Gateway console set a resource-based policy. The policy grants API Gateway permission to invoke the authorizer Lambda function. You can also choose to enter 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.

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. Paste the aws lambda add-permission command string that you copied in a previous step into an AWS CLI window that is configured for your second account. Replace AUTHORIZER_ID with your authorizer's ID. This will grant your first account access to your second account's Lambda authorizer function.