# HttpApiAuth
<a name="sam-property-httpapi-httpapiauth"></a>

Configure authorization to control access to your Amazon API Gateway HTTP API.

For more information about configuring access to HTTP APIs, see [Controlling and managing access to an HTTP API in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-access-control.html) in the *API Gateway Developer Guide*.

## Syntax
<a name="sam-property-httpapi-httpapiauth-syntax"></a>

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

### YAML
<a name="sam-property-httpapi-httpapiauth-syntax.yaml"></a>

```
  [Authorizers](#sam-httpapi-httpapiauth-authorizers): OAuth2Authorizer | LambdaAuthorizer
  [DefaultAuthorizer](#sam-httpapi-httpapiauth-defaultauthorizer): String
  [EnableIamAuthorizer](#sam-httpapi-httpapiauth-enableiamauthorizer): Boolean
```

## Properties
<a name="sam-property-httpapi-httpapiauth-properties"></a>

 `Authorizers`   <a name="sam-httpapi-httpapiauth-authorizers"></a>
The authorizer used to control access to your API Gateway API.  
*Type*: [OAuth2Authorizer](sam-property-httpapi-oauth2authorizer.md) \$1 [LambdaAuthorizer](sam-property-httpapi-lambdaauthorizer.md)  
*Required*: No  
*Default*: None  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.  
*Additional notes*: AWS SAM adds the authorizers to the OpenAPI definition.

 `DefaultAuthorizer`   <a name="sam-httpapi-httpapiauth-defaultauthorizer"></a>
Specify the default authorizer to use for authorizing API calls to your API Gateway API. You can specify `AWS_IAM` as a default authorizer if `EnableIamAuthorizer` is set to `true`. Otherwise, specify an authorizer that you've defined in `Authorizers`.  
*Type*: String  
*Required*: No  
*Default*: None  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `EnableIamAuthorizer`   <a name="sam-httpapi-httpapiauth-enableiamauthorizer"></a>
Specify whether to use IAM authorization for the API route.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-httpapi-httpapiauth--examples"></a>

### OAuth 2.0 Authorizer
<a name="sam-property-httpapi-httpapiauth--examples--oauth-2.0-authorizer"></a>

OAuth 2.0 authorizer example

#### YAML
<a name="sam-property-httpapi-httpapiauth--examples--oauth-2.0-authorizer--yaml"></a>

```
Auth:
  Authorizers:
    OAuth2Authorizer:
      AuthorizationScopes:
        - scope1
        - scope2
      JwtConfiguration:
        issuer: "https://www.example.com/v1/connect/oauth2"
        audience:
          - MyApi
      IdentitySource: "$request.querystring.param"
  DefaultAuthorizer: OAuth2Authorizer
```

### IAM authorizer
<a name="sam-property-httpapi-httpapiauth--examples--iam-authorizer"></a>

IAM authorizer example

#### YAML
<a name="sam-property-httpapi-httpapiauth--examples--iam-authorizer--yaml"></a>

```
Auth:
  EnableIamAuthorizer: true
  DefaultAuthorizer: AWS_IAM
```

# LambdaAuthorizer
<a name="sam-property-httpapi-lambdaauthorizer"></a>

Configure a Lambda authorizer to control access to your Amazon API Gateway HTTP API with an AWS Lambda function.

For more information and examples, see [Working with AWS Lambda authorizers for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html) in the *API Gateway Developer Guide*.

## Syntax
<a name="sam-property-httpapi-lambdaauthorizer-syntax"></a>

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

### YAML
<a name="sam-property-httpapi-lambdaauthorizer-syntax.yaml"></a>

```
  [AuthorizerPayloadFormatVersion](#sam-httpapi-lambdaauthorizer-authorizerpayloadformatversion): String
  EnableFunctionDefaultPermissions: Boolean
  [EnableSimpleResponses](#sam-httpapi-lambdaauthorizer-enablesimpleresponses): Boolean
  [FunctionArn](#sam-httpapi-lambdaauthorizer-functionarn): String
  [FunctionInvokeRole](#sam-httpapi-lambdaauthorizer-functioninvokerole): String
  [Identity](#sam-httpapi-lambdaauthorizer-identity): LambdaAuthorizationIdentity
```

## Properties
<a name="sam-property-httpapi-lambdaauthorizer-properties"></a>

 `AuthorizerPayloadFormatVersion`   <a name="sam-httpapi-lambdaauthorizer-authorizerpayloadformatversion"></a>
Specifies the format of the payload sent to an HTTP API Lambda authorizer. Required for HTTP API Lambda authorizers.  
This is passed through to the `authorizerPayloadFormatVersion` section of an `x-amazon-apigateway-authorizer` in the `securitySchemes` section of an OpenAPI definition.  
*Valid values*: `1.0` or `2.0`  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `EnableFunctionDefaultPermissions`   <a name="sam-httpapi-lambdaauthorizer-enablefunctiondefaultpermissions"></a>
By default, the HTTP API resource is not granted permission to invoke the Lambda authorizer. Specify this property as `true` to automatically create permissions between your HTTP API resource and your Lambda authorizer.  
*Type*: Boolean  
*Required*: No  
*Default value*: `false`  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `EnableSimpleResponses`   <a name="sam-httpapi-lambdaauthorizer-enablesimpleresponses"></a>
Specifies whether a Lambda authorizer returns a response in a simple format. By default, a Lambda authorizer must return an AWS Identity and Access Management (IAM) policy. If enabled, the Lambda authorizer can return a boolean value instead of an IAM policy.  
This is passed through to the `enableSimpleResponses` section of an `x-amazon-apigateway-authorizer` in the `securitySchemes` section of an OpenAPI definition.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionArn`   <a name="sam-httpapi-lambdaauthorizer-functionarn"></a>
The Amazon Resource Name (ARN) of the Lambda function that provides authorization for the API.  
This is passed through to the `authorizerUri` section of an `x-amazon-apigateway-authorizer` in the `securitySchemes` section of an OpenAPI definition.  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionInvokeRole`   <a name="sam-httpapi-lambdaauthorizer-functioninvokerole"></a>
The ARN of the IAM role that has the credentials required for API Gateway to invoke the authorizer function. Specify this parameter if your function's resource-based policy doesn't grant API Gateway `lambda:InvokeFunction` permission.  
This is passed through to the `authorizerCredentials` section of an `x-amazon-apigateway-authorizer` in the `securitySchemes` section of an OpenAPI definition.  
For more information, see [Create a Lambda authorizer](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html#http-api-lambda-authorizer.example-create) in the *API Gateway Developer Guide*.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Identity`   <a name="sam-httpapi-lambdaauthorizer-identity"></a>
Specifies an `IdentitySource` in an incoming request for an authorizer.  
This is passed through to the `identitySource` section of an `x-amazon-apigateway-authorizer` in the `securitySchemes` section of an OpenAPI definition.  
*Type*: [LambdaAuthorizationIdentity](sam-property-httpapi-lambdaauthorizationidentity.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-httpapi-lambdaauthorizer--examples"></a>

### LambdaAuthorizer
<a name="sam-property-httpapi-lambdaauthorizer--examples--lambdaauthorizer"></a>

LambdaAuthorizer example

#### YAML
<a name="sam-property-httpapi-lambdaauthorizer--examples--lambdaauthorizer--yaml"></a>

```
Auth:
  Authorizers:
    MyLambdaAuthorizer:
      AuthorizerPayloadFormatVersion: 2.0
      FunctionArn:
        Fn::GetAtt:
          - MyAuthFunction
          - Arn
      FunctionInvokeRole:
        Fn::GetAtt:
          - LambdaAuthInvokeRole
          - Arn
      Identity:
        Headers:
          - Authorization
```

# LambdaAuthorizationIdentity
<a name="sam-property-httpapi-lambdaauthorizationidentity"></a>

Use property can be used to specify an IdentitySource in an incoming request for a Lambda authorizer. For more information about identity sources, see [Identity sources](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html#http-api-lambda-authorizer.identity-sources) in the *API Gateway Developer Guide*.

## Syntax
<a name="sam-property-httpapi-lambdaauthorizationidentity-syntax"></a>

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

### YAML
<a name="sam-property-httpapi-lambdaauthorizationidentity-syntax.yaml"></a>

```
  [Context](#sam-httpapi-lambdaauthorizationidentity-context): List
  [Headers](#sam-httpapi-lambdaauthorizationidentity-headers): List
  [QueryStrings](#sam-httpapi-lambdaauthorizationidentity-querystrings): List
  [ReauthorizeEvery](#sam-httpapi-lambdaauthorizationidentity-reauthorizeevery): Integer
  [StageVariables](#sam-httpapi-lambdaauthorizationidentity-stagevariables): List
```

## Properties
<a name="sam-property-httpapi-lambdaauthorizationidentity-properties"></a>

 `Context`   <a name="sam-httpapi-lambdaauthorizationidentity-context"></a>
Converts the given context strings to a list of mapping expressions in the format `$context.contextString`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Headers`   <a name="sam-httpapi-lambdaauthorizationidentity-headers"></a>
Converts the headers to a list of mapping expressions in the format `$request.header.name`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `QueryStrings`   <a name="sam-httpapi-lambdaauthorizationidentity-querystrings"></a>
Converts the given query strings to a list of mapping expressions in the format `$request.querystring.queryString`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ReauthorizeEvery`   <a name="sam-httpapi-lambdaauthorizationidentity-reauthorizeevery"></a>
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. The maximum value is 3600, or 1 hour.  
*Type*: Integer  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `StageVariables`   <a name="sam-httpapi-lambdaauthorizationidentity-stagevariables"></a>
Converts the given stage variables to a list of mapping expressions in the format `$stageVariables.stageVariable`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-httpapi-lambdaauthorizationidentity--examples"></a>

### LambdaRequestIdentity
<a name="sam-property-httpapi-lambdaauthorizationidentity--examples--lambdarequestidentity"></a>

Lambda request identity example

#### YAML
<a name="sam-property-httpapi-lambdaauthorizationidentity--examples--lambdarequestidentity--yaml"></a>

```
Identity:
  QueryStrings:
    - auth
  Headers:
    - Authorization
  StageVariables:
    - VARIABLE
  Context:
    - authcontext
  ReauthorizeEvery: 100
```

# OAuth2Authorizer
<a name="sam-property-httpapi-oauth2authorizer"></a>

Definition for an OAuth 2.0 authorizer, also known to as a JSON Web Token (JWT) authorizer.

For more information, see [Controlling access to HTTP APIs with JWT authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) in the *API Gateway Developer Guide*.

## Syntax
<a name="sam-property-httpapi-oauth2authorizer-syntax"></a>

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

### YAML
<a name="sam-property-httpapi-oauth2authorizer-syntax.yaml"></a>

```
  [AuthorizationScopes](#sam-httpapi-oauth2authorizer-authorizationscopes): List
  [IdentitySource](#sam-httpapi-oauth2authorizer-identitysource): String
  [JwtConfiguration](#sam-httpapi-oauth2authorizer-jwtconfiguration): Map
```

## Properties
<a name="sam-property-httpapi-oauth2authorizer-properties"></a>

 `AuthorizationScopes`   <a name="sam-httpapi-oauth2authorizer-authorizationscopes"></a>
List of authorization scopes for this authorizer.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `IdentitySource`   <a name="sam-httpapi-oauth2authorizer-identitysource"></a>
Identity source expression for this authorizer.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `JwtConfiguration`   <a name="sam-httpapi-oauth2authorizer-jwtconfiguration"></a>
JWT configuration for this authorizer.  
This is passed through to the `jwtConfiguration` section of an `x-amazon-apigateway-authorizer` in the `securitySchemes` section of an OpenAPI definition.  
Properties `issuer` and `audience` are case insensitive and can be used either lowercase as in OpenAPI or uppercase `Issuer` and `Audience` as in [ AWS::ApiGatewayV2::Authorizer](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigatewayv2-authorizer-jwtconfiguration.html). 
*Type*: Map  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-httpapi-oauth2authorizer--examples"></a>

### OAuth 2.0 authorizer
<a name="sam-property-httpapi-oauth2authorizer--examples--oauth-2.0-authorizer"></a>

OAuth 2.0 authorizer Example

#### YAML
<a name="sam-property-httpapi-oauth2authorizer--examples--oauth-2.0-authorizer--yaml"></a>

```
Auth:
  Authorizers:
    OAuth2Authorizer:
      AuthorizationScopes:
        - scope1
      JwtConfiguration:
        issuer: "https://www.example.com/v1/connect/oauth2"
        audience:
          - MyApi
      IdentitySource: "$request.querystring.param"
  DefaultAuthorizer: OAuth2Authorizer
```