Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » Amazon API Gateway Resource Types Reference » AWS::ApiGateway::Authorizer

AWS::ApiGateway::Authorizer

The AWS::ApiGateway::Authorizer resource creates an authorization layer that Amazon API Gateway (API Gateway) activates for methods that have authorization enabled. API Gateway activates the authorizer when a client calls those methods.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::ApiGateway::Authorizer",
  "Properties" : {
    "AuthType" : String,
    "AuthorizerCredentials" : String,
    "AuthorizerResultTtlInSeconds" : Integer,
    "AuthorizerUri" : String,
    "IdentitySource" : String,
    "IdentityValidationExpression" : String,
    "Name" : String,
    "ProviderARNs" : [ String, ... ],
    "RestApiId" : String,
    "Type" : String
  }
}

YAML

Type: AWS::ApiGateway::Authorizer
Properties:
  AuthType: String
  AuthorizerCredentials: String
  AuthorizerResultTtlInSeconds: Integer
  AuthorizerUri: String
  IdentitySource: String
  IdentityValidationExpression: String
  Name: String
  ProviderARNs:
    - String
  RestApiId: String
  Type: String

Properties

For more information, including valid values, constraints, and examples of specifying each property, see Authorizer in the API Gateway API Reference.

AuthType

An optional customer-defined field that's used in Swagger imports and exports without functional impact.

Required: No

Type: String

Update requires: No interruption

AuthorizerCredentials

The credentials that are required for the authorizer. To specify an AWS Identity and Access Management (IAM) role that API Gateway assumes, specify the role's Amazon Resource Name (ARN). To use resource-based permissions on the AWS Lambda (Lambda) function, specify null.

Required: No

Type: String

Update requires: No interruption

AuthorizerResultTtlInSeconds

The time-to-live (TTL) period, in seconds, that specifies how long API Gateway caches authorizer results. If you specify a value greater than 0, API Gateway caches the authorizer responses. By default, API Gateway sets this property to 300. The maximum value is 3600, or 1 hour.

Required: No

Type: Integer

Update requires: No interruption

AuthorizerUri

The authorizer's Uniform Resource Identifier (URI). If you specify TOKEN for the authorizer's Type property, specify a Lambda function URI that has the form arn:aws:apigateway:region:lambda:path/path. The path usually has the form /2015-03-31/functions/LambdaFunctionARN/invocations.

Required: Conditional. Specify this property for Lambda functions only.

Type: String

Update requires: No interruption

IdentitySource

The source of the identity in an incoming request.

If you specify TOKEN or COGNITO_USER_POOLS for the Type property, specify a header mapping expression using the form method.request.header.name, where name is the name of a custom authorization header that clients submit as part of their requests.

If you specify REQUEST for the Type property, specify a comma-separated string of one or more mapping expressions of the specified request parameter using the form method.request.parameter.name. For supported parameter types, see Configure Lambda Authorizer Using the API Gateway Console in the API Gateway Developer Guide.

Required: Yes

Type: String

Update requires: No interruption

IdentityValidationExpression

A validation expression for the incoming identity. If you specify TOKEN for the authorizer's Type property, specify a regular expression. API Gateway uses the expression to attempt to match the incoming client token, and proceeds if the token matches. If the token doesn't match, API Gateway responds with a 401 (unauthorized request) error code.

Required: No

Type: String

Update requires: No interruption

Name

The name of the authorizer.

Required: Yes

Type: String

Update requires: No interruption

ProviderARNs

A list of the Amazon Cognito user pool Amazon Resource Names (ARNs) to associate with this authorizer. For more information, see Use Amazon Cognito User Pools in the API Gateway Developer Guide.

Required: No

Type: List of String values

Update requires: No interruption

RestApiId

The ID of the RestApi resource that API Gateway creates the authorizer in.

Required: Yes

Type: String

Update requires: Replacement

Type

The type of authorizer. Valid values include:

  • TOKEN: A custom authorizer that uses a Lambda function.

  • COGNITO_USER_POOLS: An authorizer that uses Amazon Cognito user pools.

  • REQUEST: An authorizer that uses a Lambda function using incoming request parameters.

Required: Yes

Type: String

Update requires: No interruption

Return Value

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the authorizer's ID, such as abcde1.

For more information about using the Ref function, see Ref.

Examples

The following examples create a custom authorizer that is an AWS Lambda function.

JSON

"Authorizer": {
  "Type": "AWS::ApiGateway::Authorizer",
  "Properties": {
    "AuthorizerCredentials": { "Fn::GetAtt": ["LambdaInvocationRole", "Arn"] },
    "AuthorizerResultTtlInSeconds": "300",
    "AuthorizerUri" : {"Fn::Join" : ["", [
      "arn:aws:apigateway:",
      {"Ref" : "AWS::Region"},
      ":lambda:path/2015-03-31/functions/",
      {"Fn::GetAtt" : ["LambdaAuthorizer", "Arn"]}, "/invocations"
    ]]},
    "Type": "TOKEN",
    "IdentitySource": "method.request.header.Auth",
    "Name": "DefaultAuthorizer",
    "RestApiId": {
      "Ref": "RestApi"
    }
  }
}

YAML

Authorizer: 
  Type: AWS::ApiGateway::Authorizer
  Properties: 
    AuthorizerCredentials: 
      Fn::GetAtt: 
        - "LambdaInvocationRole"
        - "Arn"
    AuthorizerResultTtlInSeconds: "300"
    AuthorizerUri: 
      Fn::Join: 
        - ""
        - 
          - "arn:aws:apigateway:"
          - Ref: "AWS::Region"
          - ":lambda:path/2015-03-31/functions/"
          - Fn::GetAtt: 
              - "LambdaAuthorizer"
              - "Arn"
          - "/invocations"
    Type: "TOKEN"
    IdentitySource: "method.request.header.Auth"
    Name: "DefaultAuthorizer"
    RestApiId: 
      Ref: "RestApi"