本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 將 Amazon Cognito 字符映射至結構描述 您可能會發現想要將身分來源新增至政策存放區，並將提供者宣告或權杖映射到您的政策存放區結構描述。您可以使用[引導式設定](policy-stores-create.md)來建立具有身分來源的政策存放區，或在建立政策存放區後手動更新結構描述，以自動化此程序。將權杖映射到結構描述後，您可以建立參考權杖的政策。 使用者指南的本節包含下列資訊： + 何時可以自動將屬性填入政策存放區結構描述 + 如何在 Verified Permissions 政策中使用 Amazon Cognito 權杖宣告 + 如何手動建置身分來源的結構描述 透過[引導式設定](policy-stores-create.md)建立的具有身分來源的 [API 連結政策存放區](policy-stores-api-userpool.md)和政策存放區，不需要手動將身分 (ID) 字符屬性映射至結構描述。您可以為 Verified Permissions 提供使用者集區中的屬性，並建立填入使用者屬性的結構描述。在 ID 字符授權中，已驗證許可會將宣告對應至委託人實體的屬性。在下列情況下，您可能需要手動將 Amazon Cognito 字符映射到您的結構描述： + 您已從範例建立空的政策存放區或政策存放區。 + 您想要將存取權杖的使用延伸到角色型存取控制 (RBAC) 之外。 + 您可以使用 Verified Permissions REST API、 AWS SDK 或 建立政策存放區 AWS CDK。 若要在 Verified Permissions 政策存放區中使用 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 請求建立的實體相符的結構描述。然後，您可以使用提供者字符中的屬性來撰寫政策。 如需有關在 Verified Permissions 中使用 Amazon Cognito ID 和存取權杖給已驗證使用者的詳細資訊，請參閱《Amazon *Amazon Cognito * [Permissions 授權](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 字符宣告視為使用者的屬性：其名稱和標題、群組成員資格、其聯絡資訊。ID 字符在*屬性型存取控制* (ABAC) 授權模型中最有用。當您希望 Verified Permissions 根據提出請求的人員分析對資源的存取時，請選擇身分來源的 ID 字符。 Amazon Cognito ID 字符適用於大多數[依賴 OIDC 的方程式庫](https://openid.net/developers/certified-openid-connect-implementations/)。它們透過額外的宣告來擴展 OIDC 的功能。您的應用程式可以使用 Amazon Cognito 使用者集區身分驗證 API 操作，或使用使用者集區託管 UI 來驗證使用者。如需詳細資訊，請參閱《 *Amazon Cognito 開發人員指南*》中的[使用 API 和端點](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html)。Amazon Cognito ID 字符中的有用宣告 *`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`是此規則的例外狀況。Verified Permissions 會將此宣告的內容映射至使用者實體的父實體。 如需 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 使用者集區建立身分來源時，您可以指定 Verified Permissions 在 授權請求中產生的委託人實體類型`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，Verified Permissions 可以驗證授權請求來自政策存放區的允許用戶端。在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 存取字符傳遞至 Verified Permissions 時，會映射至內容物件。您可以使用 參考存取字符的屬性`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 Permissions 啟動時，建議的 Amazon Cognito 字符宣告結構描述，例如 `cognito:groups`，並將這些冒號分隔字串`custom:store`轉換為使用 `.` 字元做為階層分隔符號。此格式稱為*點表示法*。例如， 的參考會在您的政策`principal.cognito.groups`中`cognito:groups`變成 。雖然您可以繼續使用此格式，但我們建議您使用[括號符號](#cognito-map-token-to-schema-things-to-know)來建置結構描述和政策。在此格式中， 的參考會在您的政策`principal["cognito:groups"]`中`cognito:groups`變成 。從 Verified Permissions 主控台自動為使用者集區 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 字符授權中，Verified Permissions 會將宣告對應至主體屬性。對於您在 Verified Permissions 主控台中建立的政策存放區，只有**空白**和**範例**政策存放區會讓您沒有身分來源，並要求您將 ID 字符授權的使用者集區屬性填入您的結構描述。存取權杖授權是以具有群組成員宣告的角色型存取控制 (RBAC) 為基礎，不會自動將其他宣告映射至政策存放區結構描述。 **不需要身分來源屬性** 當您在 Verified Permissions 主控台中建立身分來源時，不會將任何屬性標記為必要。這可防止遺失宣告導致授權請求中的驗證錯誤。您可以視需要將屬性設定為必要，但這些屬性必須存在於所有授權請求中。 **RBAC 不需要結構描述中的屬性** 身分來源的結構描述取決於您在新增身分來源時建立的實體關聯。身分來源會將一個宣告對應至使用者實體類型，並將一個宣告對應至群組實體類型。這些實體映射是身分來源組態的核心。透過此最低資訊，您可以在角色型存取控制 (RBAC) 模型中撰寫政策，為使用者可能所屬的特定使用者和特定群組執行授權動作。在結構描述中新增權杖宣告可延長政策存放區的授權範圍。來自 ID 權杖的使用者屬性具有可促成屬性型存取控制 (ABAC) 授權的使用者相關資訊。存取字符的內容屬性具有 OAuth 2.0 範圍等資訊，可以提供來自提供者的其他存取控制資訊，但需要額外的結構描述修改。 Verified Permissions 主控台中的**使用 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 或存取權杖的授權。此資訊會影響 Verified Permissions 套用至您政策存放區的結構描述屬性，以及 API 閘道 API 的 Lambda 授權方語法。特別是如果您希望從 ID 字符宣告自動映射到 Verified Permissions 主控台中的屬性中受益，請在建立身分來源之前提早決定要處理的字符類型。變更字符類型需要大量精力來重構您的政策和結構描述。下列主題說明搭配政策存放區使用 ID 和存取權杖。 **Cedar 剖析器需要某些字元的括號** 政策通常會參考 等格式的結構描述屬性`principal.username`。在字符宣告名稱中`/`可能出現的大多數非英數字元，例如 `.`、 `:`或 ，Verified Permissions 無法剖析 `principal.cognito:username`或 等條件值`context.ip-address`。您必須改為使用括號表示法來格式化這些條件`context["ip-address"]`，格式分別為 `principal["cognito:username"]`或 。底線字元`_`是宣告名稱中的有效字元，也是此要求的唯一非英數字元例外狀況。 此類型主體屬性的部分範例結構描述如下所示： ``` "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)。