本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 与 API 关联的策略存储
<a name="policy-stores-api-userpool"></a>

一个常见的用例是使用亚马逊验证权限来授权用户访问 APIs 托管在 Amazon API Gateway 上。使用 Amazon 控制台中的向导，您可以为在 [Amazon](https://www.amazonaws.cn/cognito) Cognito 中管理的用户或任何 OIDC 身份提供商 (IdP) 创建基于角色的访问策略，并部署调 Amazon Lambda 用已验证权限的授权方来评估这些策略。

要完成向导，请在[创建新的策略存储](policy-stores-create.md)时选择**设置方式 API Gateway 和身份提供商**，然后按照步骤进行操作。

已创建与 API 关联的策略存储，它会为授权请求预置您的授权模型和资源。策略存储库有一个身份源和一个连接到已验证权限的 Lambda 授权者 API Gateway 。创建策略存储后，您可以根据用户的群组成员资格授权 API 请求。例如，“已验证权限” 只能向属于该`Directors`群组成员的用户授予访问权限。

随着应用程序的增长，您可以使用 C [edar 策略](https://docs.cedarpolicy.com/)语言实现具有用户属性和范围 OAuth 2.0 的精细授权。例如，“已验证权限” 只能向在域中拥有`email`属性的用户授予访问权限`mycompany.co.uk`。

为 API 设置授权模型后，剩下的责任是对用户进行身份验证并在应用程序中生成 API 请求，以及维护您的策略存储。

要观看演示，请查看*Amazon Web Services YouTube 频道*上的 [Amazon 已验证权限-快速入门概述和演示](https://www.youtube.com/watch?v=OBrSrzfuWhQ)。

**Topics**
+ [经过验证的权限如何授权 API 请求](#policy-stores-api-userpool-how-it-works)
+ [API 关联策略存储的注意事项](#policy-stores-api-userpool-considerations)
+ [添加基于属性的访问控制 (ABAC)](#policy-stores-api-userpool-abac)
+ [通过以下方式进入生产阶段 Amazon CloudFormation](policy-stores-api-userpool-considerations-production.md)
+ [对 API 关联策略存储进行故障排除](policy-stores-api-userpool-considerations-troubleshooting.md)

**重要**  
您在已验证权限控制台中**使用设置 API Gateway 方式和身份源**选项创建的策略存储不适用于立即部署到生产环境。使用初始策略存储，完成授权模型并将策略存储资源导出到 CloudFormation。使用以编程方式将已验证的权限部署到生产环境中。[Amazon Cloud Development Kit (Amazon CDK)](https://www.amazonaws.cn/cdk)有关更多信息，请参阅 [通过以下方式进入生产阶段 Amazon CloudFormation](policy-stores-api-userpool-considerations-production.md)。

在关联到 API 和身份源的策略存储中，您的应用程序在向 API 发出请求时会在授权标头中显示用户池令牌。您的策略存储库的身份源为已验证的权限提供令牌验证。令牌与 [IsAuthorizedWithToken](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)API 形成授权请求。`principal`Verified Permissions 围绕用户的群组成员资格制定策略，如身份 (ID) 和访问令牌（例如`cognito:groups`用户池）中的群组声明中所示。您的 API 在 Lambda 授权机构中处理来自您的应用程序的令牌，并将其提交给已验证权限以做出授权决定。当您的 API 收到来自 Lambda 授权方的授权决定时，它会将请求传递给您的数据源或拒绝该请求。

**身份来源和带有已验证权限的 API Gateway 授权的组成部分**
+ 用于对[Amazon Cognito](https://docs.amazonaws.cn/cognito/latest/developerguide/cognito-user-identity-pools.html)用户进行身份验证和分组的用户池或 OIDC IdP。用户的令牌会填充群组成员资格以及已验证权限在您的策略存储中评估的委托人或上下文。
+ 一个 [API Gateway](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-rest-api.html)REST API。例如，“已验证权限” 定义来自 API 路径和 API 方法的操作`MyAPI::Action::get /photo`。
+ 一个 Lambda 函数和一个 API 的 Lam [bda 授权者](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)。Lambda 函数从您的用户池中获取不记名令牌，请求已验证权限的授权，然后将决策返回给。 API Gateway**设置方式 API Gateway 和身份源**工作流程会自动为您创建此 Lambda 授权方。
+ 已验证权限策略存储。策略存储标识源是您的 Amazon Cognito 用户池或 OIDC 提供商组。策略存储架构反映了您的 API 的配置，策略将用户组与允许的 API 操作关联起来。
+ 一种通过您的 IdP 对用户进行身份验证并将令牌附加到 API 请求的应用程序。

## 经过验证的权限如何授权 API 请求
<a name="policy-stores-api-userpool-how-it-works"></a>

当您创建新的策略存储并选择**设置方式和身份源选项时，Ver API Gateway i** fied Permissions 会创建策略存储架构和策略。架构和策略反映了 API 操作以及您想要授权执行这些操作的用户组。[经过验证的权限还会创建 Lambda 函数和授权者。](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)

![\[该图表显示了使用 Amazon API Gateway、Amazon Cognito 和亚马逊验证权限的授权请求流程。\]](http://docs.amazonaws.cn/verifiedpermissions/latest/userguide/images/api-authorization.png)


1. 您的用户通过 Amazon Cognito 或其他 OIDC IdP 使用您的应用程序登录。IdP 颁发包含用户信息的 ID 和访问令牌。

1. 您的应用程序存储 JWTs. 有关更多信息，请参阅《*Amazon Cognito 开发者指南》*中的在[用户池中使用令牌](https://docs.amazonaws.cn/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)。

1. 您的用户请求您的应用程序必须从外部 API 检索的数据。

1. 您的应用程序从中的 REST API 请求数据 API Gateway。它会附加 ID 或访问令牌作为请求标头。

1. 如果您的 API 有用于授权决策的缓存，则它会返回之前的响应。如果缓存已禁用或 API 没有当前缓存，则 API Gateway 会将请求参数传递给基于[令牌的 Lambda 授权](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)者。

1. Lambda 函数通过 API 向已验证权限策略存储发送授权请求。[IsAuthorizedWithToken](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)Lambda 函数传递授权决策的要素：

   1. 用户的代币作为委托人。

   1. 例如，API 方法与 API 路径相结合`GetPhoto`，作为操作。

   1. `Application`作为资源的术语。

1. 已验证的权限会验证令牌。有关如何验证 Amazon Cognito 令牌的更多信息，请参阅*Amazon Cognito 开发者指南*中的[使用亚马逊验证权限进行授权](https://docs.amazonaws.cn/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)。

1. Verified Permissions 会根据您的策略存储中的策略评估授权请求并返回授权决定。

1. Lambda 授权方会向返回`Allow`或`Deny`响应。 API Gateway

1. API 会向您的应用程序返回数据或`ACCESS_DENIED`响应。您的应用程序处理并显示 API 请求的结果。

## API 关联策略存储的注意事项
<a name="policy-stores-api-userpool-considerations"></a>

在已验证权限控制台中构建与 API 关联的策略存储库时，您正在为最终的生产部署创建测试。在进入生产环境之前，请为 API 和用户池建立固定配置。请考虑以下因素：

**API Gateway 缓存响应**  
在与 API 关联的策略存储中，已验证权限会创建授权**缓存 TTL 为 120 秒的 Lambda 授权方**。您可以调整此值或在授权者中关闭缓存。在启用了缓存的授权方中，您的授权方每次都会返回相同的响应，直到 TTL 到期。这可以将用户池令牌的有效寿命延长一段时间，该持续时间等于请求阶段的缓存 TTL。

**Amazon Cognito 群组可以重复使用**  
Amazon Verified Permissions 根据用户 ID 或访问令牌中的`cognito:groups`声明来确定用户池用户的群组成员资格。此声明的值是该用户所属的用户池组的友好名称数组。您无法将用户池组与唯一标识符相关联。  
您删除并重新创建的用户池组与策略存储中的同名用户池组与同一个组相同。从用户池中删除组时，请从策略存储中删除对该组的所有引用。

**API 派生的命名空间和架构是 point-in-time**  
经过验证的权限会在某个*时间点捕获您的 API：它仅在*您创建策略存储时查询您的 API。当 API 的架构或名称发生变化时，您必须更新您的策略存储和 Lambda 授权机构，或者创建一个新的 API 关联策略存储。Verified Permissions 从您的 API 名称派生出策略存储[命](https://docs.cedarpolicy.com/schema/schema.html#schema-namespace)名空间。

**Lambda 函数没有 VPC 配置**  
已验证权限为您的 API 授权方创建的 Lambda 函数将在默认 VPC 中启动。默认情况下。 APIs 将网络访问权限限制为私有的 Lambda 函数 VPCs 无法与授权具有已验证权限的访问请求的 Lambda 函数通信。

**“已验证权限” 在中部署授权方资源 CloudFormation**  
要创建与 API 关联的策略存储，您必须使用高权限 Amazon 委托人登录已验证权限控制台。该用户部署了一个 Amazon CloudFormation 堆栈，该堆栈可以跨多个 Amazon Web Services 服务堆栈创建资源。该委托人必须有权在已验证的权限、 IAM、Lambda 和中添加和修改资源。 API Gateway最佳做法是，不要与组织中的其他管理员共享这些凭证。  
[通过以下方式进入生产阶段 Amazon CloudFormation](policy-stores-api-userpool-considerations-production.md)有关已验证权限创建的资源的概述，请参阅。

## 添加基于属性的访问控制 (ABAC)
<a name="policy-stores-api-userpool-abac"></a>

与 IdP 的典型身份验证会话会返回 ID 和访问令牌。您可以将这两种令牌类型中的任何一种作为不记名令牌传递给您的 API 的应用程序请求。根据您在创建策略存储时所做的选择，“验证权限” 需要两种类型的令牌之一。这两种类型都包含有关用户群组成员资格的信息。有关令牌类型的更多信息 Amazon Cognito，请参阅《*Amazon Cognito 开发者指南》*中的在[用户池中使用令牌](https://docs.amazonaws.cn/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)。

创建策略存储后，您可以添加和扩展策略。例如，您可以在将新群组添加到用户池时向策略中添加新群组。由于您的策略存储已经知道您的用户池以令牌形式呈现群组的方式，因此您可以使用新策略允许任何新群组执行一系列操作。

您可能还想将基于群组的策略评估模型扩展为基于用户属性的更精确的模型。用户池令牌包含其他用户信息，这些信息可能有助于做出授权决策。

**ID 令牌**  
ID 令牌代表用户的属性，具有高度的细粒度访问控制。要评估电子邮件地址、电话号码或部门和经理等自定义属性，请评估 ID 令牌。

**访问令牌**  
访问令牌代表用户在 OAuth 2.0 范围内的权限。要添加授权层或设置对额外资源的请求，请评估访问令牌。例如，您可以验证用户是否属于相应的群组，*并且*其范围通常用于授权 API 的访问权限。`PetStore.read`用户池可以通过[资源服务器](https://docs.amazonaws.cn/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html)向令牌添加自定义范围，并在[运行时自定义令牌](https://docs.amazonaws.cn/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html#user-pool-lambda-pre-token-generation-accesstoken)。

有关处理 ID 和[访问 Amazon Cognito 令牌](cognito-map-token-to-schema.md)声明的策略示例，请参阅[将令牌映射到架构和将 OIDC 令牌](oidc-map-token-to-schema.md)映射到架构。