Controlling access to API Gateway APIs - AWS Serverless Application Model

Controlling access to API Gateway APIs

To control who can access your Amazon API Gateway APIs, you can enable authorization within your AWS SAM template.

AWS SAM supports several mechanisms for controlling access to your API Gateway APIs. The set of supported mechanisms differs between AWS::Serverless::HttpApi and AWS::Serverless::Api resource types.

The following table summarizes the mechanisms that each resource type supports.

Mechanisms for controlling access AWS::Serverless::HttpApi AWS::Serverless::Api
Lambda authorizers
IAM permissions
Amazon Cognito user pools ✓ *
API keys
Resource policies
OAuth 2.0/JWT authorizers

* You can use Amazon Cognito as a JSON Web Token (JWT) issuer with the AWS::Serverless::HttpApi resource type.

  • Lambda authorizers – A Lambda authorizer (formerly known as a custom authorizer) is a Lambda function that you provide to control access to your API. When your API is called, this Lambda function is invoked with a request context or an authorization token that the client application provides. The Lambda function responds whether the caller is authorized to perform the requested operation.

    Both the AWS::Serverless::HttpApi and AWS::Serverless::Api resource types support Lambda authorizers.

    For more information about Lambda authorizers with AWS::Serverless::HttpApi, see Working with AWS Lambda authorizers for HTTP APIs in the API Gateway Developer Guide. For more information about Lambda authorizers with AWS::Serverless::Api, see Use API Gateway Lambda authorizers in the API Gateway Developer Guide.

    For examples of Lambda authorizers for either resource type, see Lambda authorizer examples.

  • IAM permissions – You can control who can invoke your API using AWS Identity and Access Management (IAM) permissions. Users calling your API must be authenticated with IAM credentials. Calls to your API succeed only if there is an IAM policy attached to the IAM user that represents the API caller, an IAM group that contains the user, or an IAM role that the user assumes.

    Only the AWS::Serverless::Api resource type supports IAM permissions.

    For more information, see Control access to an API with IAM permissions in the API Gateway Developer Guide. For an example, see IAM permission example.

  • Amazon Cognito user pools – Amazon Cognito user pools are user directories in Amazon Cognito. A client of your API must first sign in a user to the user pool and obtain an identity or access token for the user. Then the client calls your API with one of the returned tokens. The API call succeeds only if the required token is valid.

    The AWS::Serverless::Api resource type supports Amazon Cognito user pools. The AWS::Serverless::HttpApi resource type supports the use of Amazon Cognito as a JWT issuer.

    For more information, see Control access to a REST API using Amazon Cognito User Pools as authorizer in the API Gateway Developer Guide. For an example, see Amazon Cognito user pool example.

  • API keys – API keys are alphanumeric string values that you distribute to application developer customers to grant access to your API.

    Only the AWS::Serverless::Api resource type supports API keys.

    For more information about API keys, see Creating and using usage plans with API keys in the API Gateway Developer Guide. For an example of API keys, see API key example.

  • Resource policies – Resource policies are JSON policy documents that you can attach to an API Gateway API. Use resource policies to control whether a specified principal (typically an IAM user or role) can invoke the API.

    Only the AWS::Serverless::Api resource type supports resource policies as a mechanism for controlling access to API Gateway APIs.

    For more information about resource policies, see Controlling access to an API with API Gateway resource policies in the API Gateway Developer Guide. For an example of resource policies, see Resource policy example.

  • OAuth 2.0/JWT authorizers – You can use JWTs as a part of OpenID Connect (OIDC) and OAuth 2.0 frameworks to control access to your APIs. API Gateway validates the JWTs that clients submit with API requests, and allows or denies requests based on token validation and, optionally, scopes in the token.

    Only the AWS::Serverless::HttpApi resource type supports OAuth 2.0/JWT authorizers.

    For more information, see Controlling access to HTTP APIs with JWT authorizers in the API Gateway Developer Guide. For an example, see OAuth 2.0/JWT authorizer example.

Choosing a mechanism to control access

The mechanism that you choose to use for controlling access to your API Gateway APIs depends on a few factors. For example, if you have a greenfield project without either authorization or access control set up, then Amazon Cognito user pools might be your best option. This is because when you set up user pools, you also automatically set up both authentication and access control.

However, if your application already has authentication set up, then using Lambda authorizers might be your best option. This is because you can call your existing authentication service and return a policy document based on the response. Also, if your application requires custom authentication or access control logic that user pools don't support, then Lambda authorizers might be your best option.

When you've chosen which mechanism to use, see the corresponding section in Examples for how to use AWS SAM to configure your application to use that mechanism.

Customizing error responses

You can use AWS SAM to customize the content of some API Gateway error responses. Only the AWS::Serverless::Api resource type supports customized API Gateway responses.

For more information about API Gateway responses, see Gateway responses in API Gateway in the API Gateway Developer Guide. For an example of customized responses, see Customized response example.

Examples