ApiAuth - Amazon Serverless Application Model
SyntaxPropertiesExamples
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).

ApiAuth

Configure authorization to control access to your API Gateway API.

For more information and examples for configuring access using Amazon SAM see Control API access with your Amazon SAM template.

Syntax

To declare this entity in your Amazon Serverless Application Model (Amazon SAM) template, use the following syntax.

Properties

AddApiKeyRequiredToCorsPreflight

If the ApiKeyRequired and Cors properties are set, then setting AddApiKeyRequiredToCorsPreflight will cause the API key to be added to the Options property.

Type: Boolean

Required: No

Default: True

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

AddDefaultAuthorizerToCorsPreflight

If the DefaultAuthorizer and Cors properties are set, then setting AddDefaultAuthorizerToCorsPreflight will cause the default authorizer to be added to the Options property in the OpenAPI section.

Type: Boolean

Required: No

Default: True

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

ApiKeyRequired

If set to true then an API key is required for all API events. For more information about API keys see Create and Use Usage Plans with API Keys in the API Gateway Developer Guide.

Type: Boolean

Required: No

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

Authorizers

The authorizer used to control access to your API Gateway API.

For more information, see Control API access with your Amazon SAM template.

Type: CognitoAuthorizer | LambdaTokenAuthorizer | LambdaRequestAuthorizer

Required: No

Default: None

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

Additional notes: SAM adds the Authorizers to the OpenApi definition of an Api.

DefaultAuthorizer

Specify a default authorizer for an API Gateway API, which will be used for authorizing API calls by default.

Note

If the Api EventSource for the function associated with this API is configured to use IAM Permissions, then this property must be set to AWS_IAM, otherwise an error will result.

Type: String

Required: No

Default: None

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

InvokeRole

Sets integration credentials for all resources and methods to this value.

CALLER_CREDENTIALS maps to arn:aws:iam::*:user/*, which uses the caller credentials to invoke the endpoint.

Valid values: CALLER_CREDENTIALS, NONE, IAMRoleArn

Type: String

Required: No

Default: CALLER_CREDENTIALS

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

ResourcePolicy

Configure Resource Policy for all methods and paths on an API.

Type: ResourcePolicyStatement

Required: No

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

Additional notes: This setting can also be defined on individual AWS::Serverless::Function using the ApiFunctionAuth. This is required for APIs with EndpointConfiguration: PRIVATE.

UsagePlan

Configures a usage plan associated with this API. For more information about usage plans see Create and Use Usage Plans with API Keys in the API Gateway Developer Guide.

This Amazon SAM property generates three additional Amazon CloudFormation resources when this property is set: an AWS::ApiGateway::UsagePlan, an AWS::ApiGateway::UsagePlanKey, and an AWS::ApiGateway::ApiKey. For information about this scenario, see UsagePlan property is specified. For general information about generated Amazon CloudFormation resources, see Generated Amazon CloudFormation resources.

Type: ApiUsagePlan

Required: No

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

Examples

CognitoAuth

Cognito Auth Example

YAML

Auth:
  Authorizers:
    MyCognitoAuth:
     UserPoolArn:
       Fn::GetAtt:
         - MyUserPool
         - Arn
     AuthType: "COGNITO_USER_POOLS"
  DefaultAuthorizer: MyCognitoAuth
  InvokeRole: CALLER_CREDENTIALS
  AddDefaultAuthorizerToCorsPreflight: false
  ApiKeyRequired: false
  ResourcePolicy:
    CustomStatements: [{
      "Effect": "Allow",
      "Principal": "*",
      "Action": "execute-api:Invoke",
      "Resource": "execute-api:/Prod/GET/pets",
      "Condition": {
          "IpAddress": {
              "aws:SourceIp": "1.2.3.4"
          }
        }
    }]
    IpRangeBlacklist:
      - "10.20.30.40"