ApiFunctionAuth - 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).

ApiFunctionAuth

Configures authorization at the event level, for a specific API, path, and method.

Syntax

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

Properties

ApiKeyRequired

Requires an API key for this API, path, and method.

Type: Boolean

Required: No

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

AuthorizationScopes

The authorization scopes to apply to this API, path, and method.

The scopes that you specify will override any scopes applied by the DefaultAuthorizer property if you have specified it.

Type: List

Required: No

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

Authorizer

The Authorizer for a specific function.

If you have a global authorizer specified for your AWS::Serverless::Api resource, you can override the authorizer by setting Authorizer to NONE. For an example, see Override a global authorizer for your Amazon API Gateway REST API.

Note

If you use the DefinitionBody property of an AWS::Serverless::Api resource to describe your API, you must use OverrideApiAuth with Authorizer to override your global authorizer. See OverrideApiAuth for more information.

Valid values: AWS_IAM, NONE, or the logical ID for any authorizer defined in your Amazon SAM template.

Type: String

Required: No

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

InvokeRole

Specifies the InvokeRole to use for AWS_IAM authorization.

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.

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

OverrideApiAuth

Specify as true to override the global authorizer configuration of your AWS::Serverless::Api resource. This property is only required if you specify a global authorizer and use the DefinitionBody property of an AWS::Serverless::Api resource to describe your API.

Note

When you specify OverrideApiAuth as true, Amazon SAM will override your global authorizer with any values provided for ApiKeyRequired, Authorizer, or ResourcePolicy. Therefore, at least one of these properties must also be specified when using OverrideApiAuth. For an example, see Override a global authorizer when DefinitionBody for AWS::Serverless::Api is specified.

Type: Boolean

Required: No

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

ResourcePolicy

Configure Resource Policy for this path 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.

Examples

Function-Auth

The following example specifies authorization at the function level.

YAML

Auth:
  ApiKeyRequired: true
  Authorizer: NONE

Override a global authorizer for your Amazon API Gateway REST API

You can specify a global authorizer for your AWS::Serverless::Api resource. The following is an example that configures a global default authorizer:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  MyApiWithLambdaRequestAuth:
    Type: AWS::Serverless::Api
    Properties:
      ...
      Auth:
        Authorizers:
          MyLambdaRequestAuth:
            FunctionArn: !GetAtt MyAuthFn.Arn
        DefaultAuthorizer: MyLambdaRequestAuth

To override the default authorizer for your Amazon Lambda function, you can specify Authorizer as NONE. The following is an example:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  ...
  MyFn:
    Type: AWS::Serverless::Function
    Properties:
      ...
      Events:
        LambdaRequest:
          Type: Api
          Properties:
            RestApiId: !Ref MyApiWithLambdaRequestAuth
            Method: GET
            Auth:
              Authorizer: NONE

Override a global authorizer when DefinitionBody for AWS::Serverless::Api is specified

When using the DefinitionBody property to describe your AWS::Serverless::Api resource, the previous override method does not work. The following is an example of using the DefinitionBody property for an AWS::Serverless::Api resource:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  MyApiWithLambdaRequestAuth:
    Type: AWS::Serverless::Api
    Properties:
      ...
      DefinitionBody:
        swagger: 2.0
        ...
        paths:
          /lambda-request:
            ...
      Auth:
        Authorizers:
          MyLambdaRequestAuth:
            FunctionArn: !GetAtt MyAuthFn.Arn
        DefaultAuthorizer: MyLambdaRequestAuth

To override the global authorizer, use the OverrideApiAuth property. The following is an example that uses OverrideApiAuth to override the global authorizer with the value provided for Authorizer:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  MyApiWithLambdaRequestAuth:
    Type: AWS::Serverless::Api
    Properties:
      ...
      DefinitionBody:
        swagger: 2-0
        ...
        paths:
          /lambda-request:
            ...
      Auth:
        Authorizers:
          MyLambdaRequestAuth:
            FunctionArn: !GetAtt MyAuthFn.Arn
        DefaultAuthorizer: MyLambdaRequestAuth
    
    MyAuthFn:
      Type: AWS::Serverless::Function
      ...
    
    MyFn:
      Type: AWS::Serverless::Function
        Properties:
          ...
          Events:
            LambdaRequest:
              Type: Api
              Properties:
                RestApiId: !Ref MyApiWithLambdaRequestAuth
                Method: GET
                Auth:
                  Authorizer: NONE
                  OverrideApiAuth: true
                Path: /lambda-token