本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 将 Amazon Cognito 令牌映射到架构 您可能会发现想要将身份源添加到策略存储中，并将地图提供商声明或令牌添加到策略存储架构中。您可以自动执行此过程，方法是使用[引导式设置](policy-stores-create.md)创建带有身份源的策略存储，或者在创建策略存储后手动更新架构。将令牌映射到架构后，您可以创建引用它们的策略。 用户指南的这一部分包含以下信息： + 何时可以自动填充策略存储架构的属性 + 如何在您的已验证权限策略中使用 Amazon Cognito 令牌声明 + 如何为身份源手动构建架构 通过[引导式设置](policy-stores-create.md)创建的 [API 关联策略存储](policy-stores-api-userpool.md)和带有身份源的策略存储不需要将身份 (ID) 令牌属性手动映射到架构。您可以为用户池中的属性提供经过验证的权限，并创建填充用户属性的架构。在 ID 令牌授权中，已验证权限将声明映射到委托人实体的属性。在以下情况下，您可能需要手动将 Amazon Cognito 令牌映射到您的架构： + 您根据示例创建了一个空的策略存储区或策略存储区。 + 您希望将访问令牌的使用范围扩展到基于角色的访问控制 (RBAC) 之外。 + 您可以使用已验证的权限 REST API、 AWS 软件开发工具包或创建策略存储 AWS CDK。 要在您的已验证权限策略存储中 Amazon Cognito 用作身份源，您的架构中必须包含提供者属性。架构是固定的，必须与提供者令牌在其中创建的实体[IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)或 [BatchIsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorizedWithToken.html)API 请求相对应。如果您创建策略存储的方式是自动从 ID 令牌中的提供者信息填充架构，那么您就可以编写策略了。如果您创建的策略存储没有身份源架构，则必须向架构中添加与使用 API 请求创建的实体相匹配的提供者属性。然后，您可以使用提供者令牌中的属性来编写策略。 有关在已验证权限中为经过身份验证的用户使用 Amazon Cognito ID 和访问令牌的更多信息，请参阅 Amazon Co *gnito 开发者指南中的使用亚马逊*[验证权限进行授权](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)。 **Topics** + [将 ID 令牌映射到架构](#cognito-map-id-token) + [映射访问令牌](#cognito-map-access-token) + [Amazon Cognito 冒号分隔的索赔的替代表示法](#cognito-colon-claims) + [关于架构映射的注意事项](#cognito-map-token-to-schema-things-to-know) ## 将 ID 令牌映射到架构 Verified Permissions 将身份令牌声明作为用户的属性进行处理：他们的姓名和头衔、群组成员资格、联系信息。ID 令牌在*基于属性的访问控制* (ABAC) 授权模型中最有用。如果您想让经过验证的权限根据谁提出请求来分析对资源的访问权限，请为您的身份来源选择 ID 令牌。 Amazon Cognito ID 令牌适用于大多数 [OIDC 依赖](https://openid.net/developers/certified-openid-connect-implementations/)方库。它们通过其他索赔扩展了OIDC的功能。您的应用程序可以通过 Amazon Cognito 用户池身份验证 API 操作或用户池托管用户界面对用户进行身份验证。有关更多信息，请参阅*Amazon Cognito 开发者指南*[中的使用 API 和终端节点](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html)。Amazon Cognito 身份令牌中的有用声明 *`cognito:username` 和 `preferred_username`* 用户名的变体。 *`sub`* 用户的唯一用户标识符 (UUID) *带`custom:`前缀的索赔* 自定义用户池属性的前缀，例如`custom:employmentStoreCode`。 *标准声明* 标准 OIDC 声称类似`email`和。`phone_number`有关更多信息，请参阅 *OpenID Connect Core 1.0 中包含勘误*集 2 的[标准声明](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)。 *`cognito:groups`* 用户的群组成员资格。在基于角色的访问控制 (RBAC) 的授权模型中，此声明提供了您可以在策略中评估的角色。 *临时索赔* 声明不是用户的财产，但在运行时由用户池[生成令牌前 Lambda](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html) 触发器添加。临时索赔与标准索赔类似，但不在标准范围内，例如`tenant`或`department`。 在引用带有`:`分隔符的 Amazon Cognito 属性的策略中，引用格式中的属性`principal["cognito:username"]`。角色声明`cognito:groups`是此规则的例外。已验证权限将此声明的内容映射到用户实体的父实体。 有关来自 Amazon Cognito 用户池的 ID 令牌结构的更多信息，请参阅*Amazon Cognito 开发者*[指南中的使用 ID 令牌](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html)。 以下示例 ID 令牌具有四种类型的属性。它包括 Amazon Cognito特定索赔`cognito:username`、自定义索赔`custom:employmentStoreCode`、标准索赔`email`和临时索赔`tenant`。 ``` { "sub": "91eb4550-XXX", "cognito:groups": [ "Store-Owner-Role", "Customer" ], "email_verified": true, "clearance": "confidential", "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE", "cognito:username": "alice", "custom:employmentStoreCode": "petstore-dallas", "origin_jti": "5b9f50a3-05da-454a-8b99-b79c2349de77", "aud": "1example23456789", "event_id": "0ed5ad5c-7182-4ecf-XXX", "token_use": "id", "auth_time": 1687885407, "department": "engineering", "exp": 1687889006, "iat": 1687885407, "tenant": "x11app-tenant-1", "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111", "email": "alice@example.com" } ``` 使用 Amazon Cognito 用户池创建身份源时，您可以指定授权请求中验证权限生成的委托人实体的类型`IsAuthorizedWithToken`。然后，作为评估该请求的一部分，您的策略会测试该主体的属性。您的架构定义身份源的委托人类型和属性，然后您可以在 Cedar 策略中引用它们。 您还可以指定要从 ID 令牌组声明中派生的群组实体的类型。在授权请求中，Verified Permissions 会将每个群组成员的声明映射到该群组实体类型。在策略中，您可以将该组实体引用为委托人。 以下示例说明了如何在 Verified Permissions 架构中反映示例身份令牌中的属性。有关编辑架构的更多信息，请参阅[编辑策略存储架构](schema-edit.md)。如果您的身份来源配置指定了主体类型 `User`，那么，您可以添加类似于以下示例的内容，以使这些属性可用于 Cedar。 ``` "User": { "shape": { "type": "Record", "attributes": { "cognito:username": { "type": "String", "required": false }, "custom:employmentStoreCode": { "type": "String", "required": false }, "email": { "type": "String" }, "tenant": { "type": "String", "required": true } } } } ``` 有关将针对此架构进行验证的策略示例，请参阅[反映 Amazon Cognito ID 令牌属性](policies-examples.md#policies-examples-cognito-id)。 ## 映射访问令牌 Verified Permissions 处理访问令牌声明，而不是作为操作属性或*上下文*属性的群组声明。除了群组成员资格外，来自您的 IdP 的访问令牌可能还包含有关 API 访问的信息。访问令牌在使用基于角色的访问控制 (RBAC) 的授权模型中很有用。依赖组成员资格以外的访问令牌声明的授权模型需要在架构配置方面付出额外的努力。 Amazon Cognito 访问令牌具有可用于授权的声明：Amazon Cognito 访问令牌中的有用声明 *`client_id`* OIDC 依赖方的客户端应用程序的 ID。使用客户端 ID，已验证权限可以验证授权请求是否来自策略存储的允许客户端。在 machine-to-machine（M2M）授权中，请求系统使用客户端密钥对请求进行授权，并提供客户端 ID 和范围作为授权证据。 *`scope`* 代表令牌持有者的访问权限的 [OAuth 2.0 范围](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)。 *`cognito:groups`* 用户的群组成员资格。在基于角色的访问控制 (RBAC) 的授权模型中，此声明提供了您可以在策略中评估的角色。 *临时索赔* 不是访问权限但是在运行时由用户池[生成令牌前 Lambda](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html) 触发器添加的声明。临时索赔与标准索赔类似，但不在标准范围内，例如`tenant`或`department`。自定义访问令牌会增加您的 AWS 账单成本。 有关来自 Amazon Cognito 用户池的访问令牌结构的更多信息，请参阅*Amazon Cognito 开发者*[指南中的使用访问令牌](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html)。 当 Amazon Cognito 访问令牌传递给 “已验证权限” 时，访问令牌会映射到上下文对象。可以使用 `context.token.attribute_name` 来引用访问令牌的属性。以下示例访问令牌同时包含 `client_id` 和 `scope` 声明。 ``` { "sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e", "cognito:groups": [ "Store-Owner-Role", "Customer" ], "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE", "client_id": "1example23456789", "origin_jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111", "event_id": "bda909cb-3e29-4bb8-83e3-ce6808f49011", "token_use": "access", "scope": "MyAPI/mydata.write", "auth_time": 1688092966, "exp": 1688096566, "iat": 1688092966, "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN2222222", "username": "alice" } ``` 以下示例说明了如何在 Verified Permissions 架构中反映示例访问令牌中的属性。有关编辑架构的更多信息，请参阅[编辑策略存储架构](schema-edit.md)。 ``` { "MyApplication": { "actions": { "Read": { "appliesTo": { "context": { "type": "ReusedContext" }, "resourceTypes": [ "Application" ], "principalTypes": [ "User" ] } } }, ... ... "commonTypes": { "ReusedContext": { "attributes": { "token": { "type": "Record", "attributes": { "scope": { "type": "Set", "element": { "type": "String" } }, "client_id": { "type": "String" } } } }, "type": "Record" } } } } ``` 有关将针对此架构进行验证的策略示例，请参阅[反映 Amazon Cognito 访问令牌属性](policies-examples.md#policies-examples-cognito-access)。 ## Amazon Cognito 冒号分隔的索赔的替代表示法 在 Verified Permissi `cognito:groups` ons 启动时， Amazon Cognito 令牌声明的推荐架构会`custom:store`将这些冒号分隔的字符串转换为使用该`.`字符作为层次结构分隔符。这种格式称为*点符号*。例如，在您的政策`principal.cognito.groups`中提及`cognito:groups`变为了。尽管您可以继续使用这种格式，但我们建议您使用[括号表示法](#cognito-map-token-to-schema-things-to-know)来构建架构和策略。在这种格式中，对的引用将`cognito:groups`变`principal["cognito:groups"]`为您的政策。从已验证权限控制台自动生成的用户池 ID 令牌架构使用方括号表示法。 您可以继续在手动构建的架构和 Amazon Cognito 身份源的策略中使用点符号。对于任何其他类型的 OIDC IdP，您不能在架构`:`或策略中使用带点符号或任何其他非字母数字字符。 点符号架构将`:`字符的每个实例嵌套为`cognito`或`custom`初始短语的子项，如以下示例所示： ``` "CognitoUser": { "shape": { "type": "Record", "attributes": { "cognito": { "type": "Record", "required": true, "attributes": { "username": { "type": "String", "required": true } } }, "custom": { "type": "Record", "required": true, "attributes": { "employmentStoreCode": { "type": "String", "required": true } } }, "email": { "type": "String" }, "tenant": { "type": "String", "required": true } } } } ``` 有关将针对此架构进行验证并使用点符号的策略示例，请参阅[使用点符号来引用属性](policies-examples.md#policies-examples-dot)。 ## 关于架构映射的注意事项 **不同标记类型的属性映射不同** 在访问令牌授权中，已验证权限将声明映射到[上下文](context.md)。在 ID 令牌授权中，已验证权限将声明映射到委托人属性。对于您在已验证权限控制台中创建的策略存储，只有**空**策略存储和**示例**策略存储才会使您没有身份来源，并要求您在架构中填充用户池属性以进行 ID 令牌授权。访问令牌授权基于基于角色的访问控制 (RBAC) 和群组成员资格声明，不会自动将其他声明映射到策略存储架构。 **身份源属性不是必需的** 在已验证权限控制台中创建身份源时，不会将任何属性标记为必填属性。这样可以防止丢失的索赔导致授权请求中的验证错误。您可以根据需要将属性设置为 required，但它们必须存在于所有授权请求中。 **RBAC 不需要架构中的属性** 身份源的架构取决于您在添加身份源时所建立的实体关联。身份源将一个声明映射到用户实体类型，将一个声明映射到群组实体类型。这些实体映射是身份源配置的核心。有了这些最少的信息，您就可以在基于角色的访问控制 (RBAC) 模型中编写对特定用户和用户可能属于的特定组执行授权操作的策略。向架构中添加令牌声明可扩展策略存储的授权范围。来自 ID 令牌的用户属性包含有关用户的信息，这些信息可以为基于属性的访问控制 (ABAC) 授权做出贡献。访问令牌的上下文属性包含诸如 OAuth 2.0 作用域之类的信息，这些信息可以提供来自提供者的额外访问控制信息，但需要进行额外的架构修改。 已验证权限控制台中的 “**使用 API Gateway 和身份提供者****进行设置” 和 “引导式设置**” 选项为架构分配 ID 令牌声明。访问令牌声明的情况并非如此。[要向架构中添加非组访问令牌声明，必须在 JSON 模式下编辑架构并添加 CommonTypes 属性。](https://docs.cedarpolicy.com/schema/json-schema.html#schema-commonTypes)有关更多信息，请参阅 [映射访问令牌](#cognito-map-access-token)。 **选择代币类型** 您的策略存储与身份源配合的方式取决于身份源配置中的一个关键决定：是处理 ID 还是访问令牌。使用 Amazon Cognito 身份提供商，您可以在创建与 API 关联的策略存储时选择令牌类型。创建与 [API 关联的策略存储](policy-stores-api-userpool.md)时，必须选择是要为 ID 还是访问令牌设置授权。此信息会影响已验证权限应用于您的策略存储的架构属性，以及适用于您的 API 的 Lambda 授权者的语法。 API Gateway 特别是如果您希望从身份令牌声明自动映射到已验证权限控制台中的属性中受益，请在创建身份源之前尽早决定要处理的令牌类型。更改令牌类型需要花费大量精力来重构您的策略和架构。以下主题介绍如何在策略存储中使用 ID 和访问令牌。 **Cedar 解析器要求某些字符使用方括号** 策略通常以类似的格式引用架构属性`principal.username`。对于令牌声明名称中可能出现的大多数非字母数字字符`:`，例如`.`、或`/`，Verified Permissions 无法解析像或这样的条件值。`principal.cognito:username` `context.ip-address`您必须改为使用`principal["cognito:username"]`或`context["ip-address"]`格式的方括号表示法来格式化这些条件。下划线字符`_`是声明名称中的有效字符，也是该要求的唯一非字母数字例外。 此类型主属性的部分示例架构如下所示： ``` "User": { "shape": { "type": "Record", "attributes": { "cognito:username": { "type": "String", "required": true }, "custom:employmentStoreCode": { "type": "String", "required": true, }, "email": { "type": "String", "required": false } } } } ``` 这种类型的上下文属性的部分示例架构如下所示： ``` "GetOrder": { "memberOf": [], "appliesTo": { "resourceTypes": [ "Order" ], "context": { "type": "Record", "attributes": { "ip-address": { "required": false, "type": "String" } } }, "principalTypes": [ "User" ] } } ``` 有关将针对此架构进行验证的策略示例，请参阅[使用方括号表示法来引用代币属性](policies-examples.md#policies-examples-brackets)。