将 OIDC 令牌映射到架构

您可能会发现想要将身份源添加到策略存储中，并将地图提供商声明或令牌添加到策略存储架构中。您可以自动执行此过程，方法是使用引导式设置创建带有身份源的策略存储，或者在创建策略存储后手动更新架构。将令牌映射到架构后，您可以创建引用它们的策略。

用户指南的这一部分包含以下信息：

何时可以自动填充策略存储架构的属性
如何为身份源手动构建架构

通过引导式设置创建的 API 关联策略存储和带有身份源的策略存储不需要将身份 (ID) 令牌属性手动映射到架构。您可以为用户池中的属性提供经过验证的权限，并创建填充用户属性的架构。在 ID 令牌授权中，已验证权限将声明映射到委托人实体的属性。

要使用 OIDC 身份提供商 (IdP) 作为已验证权限策略存储中的身份源，您的架构中必须包含提供者属性。架构是固定的，必须与提供者令牌创建的实体IsAuthorizedWithToken或 BatchIsAuthorizedWithTokenAPI 请求相对应。如果您创建策略存储的方式是自动从 ID 令牌中的提供者信息填充架构，那么您就可以编写策略了。如果您创建的策略存储没有身份源架构，则必须向架构中添加与使用 API 请求创建的实体相匹配的提供者属性。然后，您可以使用提供者令牌中的属性来编写策略。

将 ID 令牌映射到架构

Verified Permissions 将身份令牌声明作为用户的属性进行处理：他们的姓名和头衔、群组成员资格、联系信息。ID 令牌在基于属性的访问控制 (ABAC) 授权模型中最有用。如果您想让经过验证的权限根据谁提出请求来分析对资源的访问权限，请为您的身份来源选择 ID 令牌。

使用 OIDC 提供商提供的 ID 令牌与使用 Amazon Cognito ID 令牌大致相同。区别在于索赔。您的 IdP 可能呈现标准的 OIDC 属性，或者具有自定义架构。在已验证权限控制台中创建新的策略存储时，可以添加带有示例 ID 令牌的 OIDC 身份源，也可以手动将令牌声明映射到用户属性。由于已验证权限不知道您的 IdP 的属性架构，因此您必须提供此信息。

有关更多信息，请参阅创建 Verified Permissions 策略存储。

以下是具有 OIDC 身份源的策略存储的示例架构。


"User": {
   "shape": {
      "type": "Record",
      "attributes": {
         "email": {
            "type": "String"
         },
         "email_verified": {
            "type": "Boolean"
         },
         "name": {
            "type": "String",
            "required": true
         },
         "phone_number": {
            "type": "String"
         },
         "phone_number_verified": {
            "type": "Boolean"
         }
      }
   }
}

有关将针对此架构进行验证的策略示例，请参阅反映 OIDC ID 令牌的属性。

映射访问令牌

Verified Permissions 处理除组声明之外的访问令牌声明作为操作属性或上下文属性。除了群组成员资格外，来自您的 IdP 的访问令牌可能还包含有关 API 访问的信息。访问令牌在使用基于角色的访问控制 (RBAC) 的授权模型中很有用。依赖组成员资格以外的访问令牌声明的授权模型需要在架构配置方面付出额外的努力。

来自外部 OIDC 提供商的大多数访问令牌都与 Amazon Cognito 访问令牌非常一致。传递给 “已验证权限” 时，OIDC 访问令牌会映射到上下文对象。可以使用 context.token.attribute_name 来引用访问令牌的属性。以下示例 OIDC 访问令牌包括基本声明示例。


{
    "sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e",
    "groups": [
        "Store-Owner-Role",
        "Customer"
    ],
    "iss": "https://auth.example.com",
    "client_id": "1example23456789",
    "aud": "https://myapplication.example.com"
    "scope": "MyAPI-Read",
    "exp": 1688096566,
    "iat": 1688092966,
    "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN2222222",
    "username": "alice"
}

以下示例说明了如何在 Verified Permissions 架构中反映示例访问令牌中的属性。有关编辑架构的更多信息，请参阅编辑策略存储架构。


{
   "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"
         }
      }
   }
}

有关将针对此架构进行验证的策略示例，请参阅反映 OIDC 访问令牌属性。

关于架构映射的注意事项

不同标记类型的属性映射不同

在访问令牌授权中，已验证权限将声明映射到上下文。在 ID 令牌授权中，已验证权限将声明映射到委托人属性。对于您在已验证权限控制台中创建的策略存储，只有空策略存储和示例策略存储才会使您没有身份来源，并要求您在架构中填充用户池属性以进行 ID 令牌授权。访问令牌授权基于基于角色的访问控制 (RBAC) 和群组成员资格声明，不会自动将其他声明映射到策略存储架构。

不需要身份源属性

在已验证权限控制台中创建身份源时，不会将任何属性标记为必填属性。这样可以防止丢失的索赔导致授权请求中的验证错误。您可以根据需要将属性设置为 required，但它们必须存在于所有授权请求中。

RBAC 不需要架构中的属性

身份源的架构取决于您在添加身份源时建立的实体关联。身份源将一个声明映射到用户实体类型，将一个声明映射到群组实体类型。这些实体映射是身份源配置的核心。有了这些最少的信息，您就可以在基于角色的访问控制 (RBAC) 模型中编写对特定用户和用户可能属于的特定组执行授权操作的策略。向架构中添加令牌声明可扩展策略存储的授权范围。来自 ID 令牌的用户属性包含可以为基于属性的访问控制 (ABAC) 授权做出贡献的用户信息。访问令牌的上下文属性包含诸如 OAuth 2.0 作用域之类的信息，这些信息可以提供来自提供者的额外访问控制信息，但需要进行额外的架构修改。

已验证权限控制台中的 “使用 API Gateway 和身份提供者进行设置” 和 “引导式设置” 选项为架构分配 ID 令牌声明。访问令牌声明的情况并非如此。要向架构中添加非组访问令牌声明，必须在 JSON 模式下编辑架构并添加 CommonTypes 属性。有关更多信息，请参阅映射访问令牌。

OIDC 团体声称支持多种格式

添加 OIDC 提供商时，您可以在 ID 或访问令牌中选择要映射到策略存储中用户的群组成员资格的群组名称。经过验证的权限可以识别以下格式的群组声明：

不带空格的字符串："groups": "MyGroup"
以空格分隔的列表:. "groups": "MyGroup1 MyGroup2 MyGroup3" 每个字符串都是一个组。
JSON（以逗号分隔）列表："groups": ["MyGroup1", "MyGroup2", "MyGroup3"]

注意

Verified Permissions 将以空格分隔的群组声明中的每个字符串解释为一个单独的群组。要将带有空格字符的组名解释为单个组，请替换或删除声明中的空格。例如，设置名为的群组My Group的格式MyGroup。

选择代币类型

您的策略存储与身份源配合的方式取决于身份源配置中的一个关键决定：是处理 ID 还是访问令牌。对于 OIDC 提供商，您必须在添加身份源时选择令牌类型。您可以选择 ID 或访问令牌，并且您的选择会将未选择的令牌类型排除在保单存储库中的处理范围之外。特别是如果您希望从身份令牌声明自动映射到已验证权限控制台中的属性中受益，请在创建身份源之前尽早决定要处理的令牌类型。更改令牌类型需要花费大量精力来重构您的策略和架构。以下主题介绍如何在策略存储中使用 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"
      ]
   }
}

有关将针对此架构进行验证的策略示例，请参阅使用方括号表示法来引用代币属性。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

编辑身份来源

客户和受众验证