本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# ApiAuth
配置授权，以控制对 API Gateway API 的访问。
有关使用配置访问权限的更多信息和示例， AWS SAM 请参阅[使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。
## 语法
要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。
### YAML
```
AddApiKeyRequiredToCorsPreflight: Boolean
[AddDefaultAuthorizerToCorsPreflight](#sam-api-apiauth-adddefaultauthorizertocorspreflight): Boolean
[ApiKeyRequired](#sam-api-apiauth-apikeyrequired): Boolean
[Authorizers](#sam-api-apiauth-authorizers): CognitoAuthorizer | LambdaTokenAuthorizer | LambdaRequestAuthorizer | AWS_IAM
[DefaultAuthorizer](#sam-api-apiauth-defaultauthorizer): String
[InvokeRole](#sam-api-apiauth-invokerole): String
[ResourcePolicy](#sam-api-apiauth-resourcepolicy): ResourcePolicyStatement
[UsagePlan](#sam-api-apiauth-usageplan): ApiUsagePlan
```
**注意**
该 `Authorizers` 属性包含 `AWS_IAM`，但无需为 `AWS_IAM` 进行额外配置。有关示例，请参阅[AWS IAM](#sam-property-api-apiauth--examples--aws_iam)。
## Properties
`AddApiKeyRequiredToCorsPreflight`
如果设置了 `ApiKeyRequired` 和 `Cors` 属性，则设置 `AddApiKeyRequiredToCorsPreflight` 会导致 API 密钥被添加到 `Options` 属性中。
*类型*：布尔值
*必需*：否
*默认值*：`True`
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
`AddDefaultAuthorizerToCorsPreflight`
如果设置了 `DefaultAuthorizer` 和 `Cors` 属性，则设置 `AddDefaultAuthorizerToCorsPreflight` 会导致默认授权方被添加到 OpenAPI 部分的 `Options` 属性中。
*类型*：布尔值
*必需*：否
*默认值*：True
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
`ApiKeyRequired`
如果设置为 true，则所有 API 事件都需要 API 密钥。有关 API 密钥的更多信息，请参阅*《API Gateway 开发人员指南》*中的[使用 API 密钥创建和使用使用计划](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。
*类型*：布尔值
*必需*：否
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
`Authorizers`
用于控制对 API Gateway API 的访问的授权方。
有关更多信息，请参阅 [使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。
*类型*:[CognitoAuthorizer](sam-property-api-cognitoauthorizer.md)\$1 [LambdaTokenAuthorizer](sam-property-api-lambdatokenauthorizer.md)\$1 [LambdaRequestAuthorizer](sam-property-api-lambdarequestauthorizer.md)\$1 AWS\$1IAM
*必需*：否
*默认值*：无
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
*其他说明*：SAM 在 Api 的 OpenApi 定义中添加了授权方。
`DefaultAuthorizer`
为 API Gateway API 指定默认授权方，默认情况下，该授权方将用于授权 API 调用。
如果将与此 API EventSource 关联的函数的 Api 配置为使用 IAM 权限，则必须将此属性设置为`AWS_IAM`，否则将导致错误。
*类型*：字符串
*必需*：否
*默认值*：无
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
`InvokeRole`
将所有资源和方法的集成凭证设置为此值。
`CALLER_CREDENTIALS` 映射到 `arn:aws:iam:::/`，后者使用调用者凭证来调用端点。
*有效值*: `CALLER_CREDENTIALS`, `NONE`, `IAMRoleArn`
*类型*：字符串
*必需*：否
*默认值*：`CALLER_CREDENTIALS`
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
`ResourcePolicy`
为 API 中的所有方法和路径配置资源策略。
*类型*：[ResourcePolicyStatement](sam-property-api-resourcepolicystatement.md)
*必需*：否
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
*附加说明*：也可以使用 [ApiFunctionAuth](sam-property-function-apifunctionauth.md) 在各个 `AWS::Serverless::Function` 中定义此设置。这是 with 所必需 APIs 的`EndpointConfiguration: PRIVATE`。
`UsagePlan`
配置与此 API 关联的使用计划。有关使用计划的更多信息，请参阅*《API Gateway 开发人员指南》*中的[使用 API 密钥创建和使用使用计划](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。
设置此 AWS SAM 属性后，此属性会额外生成三个 CloudFormation 资源：a [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html)、a 和[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html)。有关此场景的更多信息，请参阅[UsagePlan 属性已指定](sam-specification-generated-resources-api.md#sam-specification-generated-resources-api-usage-plan)。有关生成的 CloudFormation 资源的一般信息，请参阅[生成的 CloudFormation 资源用于 AWS SAM](sam-specification-generated-resources.md)。
*类型*：[ApiUsagePlan](sam-property-api-apiusageplan.md)
*必需*：否
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。
## 示例
### CognitoAuth
Cognito 身份验证示例
#### 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"
}
}
}]
IpRangeDenylist:
- "10.20.30.40"
```
### AWS IAM
AWS IAM 示例
#### YAML
```
Auth:
Authorizers: AWS_IAM
```