本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Amazon Cognito 身分來源 Verified Permissions 與 Amazon Cognito 使用者集區緊密搭配運作。 Amazon Cognito JWTs具有可預測的結構。Verified Permissions 會辨識此結構，並從其中包含的資訊中獲益上限。例如，您可以使用 ID 字符或存取權杖實作角色型存取控制 (RBAC) 授權模型。 新的 Amazon Cognito 使用者集區身分來源需要以下資訊： + AWS 區域。 + 使用者集區 ID。 + 您要與身分來源建立關聯的主體實體類型，例如 `MyCorp::User`。 + 您要與身分來源建立關聯的委託人群組實體類型，例如 `MyCorp::UserGroup`。 + 使用者集區的用戶端 IDs，您想要授權 向您的政策存放區提出請求。 由於 Verified Permissions 僅適用於相同 中的 Amazon Cognito 使用者集區 AWS 帳戶，因此您無法在另一個帳戶中指定身分來源。Verified Permissions 會將*實體字首* - 您必須在對使用者集區主體採取行動的政策中參考的身分來源識別符 - 設定為使用者集區的 ID，例如 `us-west-2_EXAMPLE`。在此情況下，您會參考該使用者集區中 ID `a1b2c3d4-5678-90ab-cdef-EXAMPLE22222`為 的使用者 `us-west-2_EXAMPLE|a1b2c3d4-5678-90ab-cdef-EXAMPLE22222` 使用者集區字符*宣告*可以包含屬性、範圍、群組、用戶端 IDs和自訂資料。[Amazon Cognito JWTs](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)能夠包含各種資訊，有助於在 Verified Permissions 中做出授權決策。其中包含： 1. 具有`cognito:`字首的使用者名稱和群組宣告 1. 使用 [自訂使用者屬性](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-custom-attributes) `custom: prefix` 1. 在執行時間新增的自訂宣告 1. OIDC 標準宣告，例如 `sub`和 `email` 我們會詳細說明這些宣告，以及如何在 的 Verified Permissions 政策中管理這些宣告[將 Amazon Cognito 字符映射至結構描述](cognito-map-token-to-schema.md)。 **重要** 雖然您可以在權 Amazon Cognito 杖過期之前撤銷權杖，但 JWTs被視為具有簽章和有效性的獨立無狀態資源。符合 [JSON Web 權杖 RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) 的服務預期會從遠端驗證權杖，而且不需要向發行者驗證權杖。這表示 Verified Permissions 可以根據稍後刪除的使用者撤銷或發出的字符授予存取權。若要降低此風險，建議您以最短的有效期間建立權杖，並在想要移除繼續使用者工作階段的授權時撤銷重新整理權杖。如需詳細資訊，請參閱[使用字符撤銷結束使用者工作階段](https://docs.aws.amazon.com/cognito/latest/developerguide/token-revocation.html) 以下範例示範如何建立參考與委託人相關聯之部分 Amazon Cognito 使用者集區宣告的政策。 ``` permit( principal, action, resource == ExampleCo::Photo::"VacationPhoto94.jpg" ) when { principal["cognito:username"]) == "alice" && principal["custom:department"]) == "Finance" }; ``` 以下範例示範如何建立政策，以參考 Cognito 使用者集區中的使用者委託人。請注意，主體 ID 採用 的形式`"|"`。 ``` permit( principal == ExampleCo::User::"us-east-1_example|a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", action, resource == ExampleCo::Photo::"VacationPhoto94.jpg" ); ``` Verified Permissions 中使用者集區身分來源的 Cedar 政策針對包含英數字元和底線 () 以外的字元的宣告名稱使用特殊語法`_`。這包括包含`:`字元的使用者集區字首宣告，例如 `cognito:username`和 `custom:department`。若要撰寫參考 `cognito:username`或 `custom:department`宣告的政策條件`principal["custom:department"]`，請分別將其寫入為 `principal["cognito:username"]`和 。 **注意** 如果字符包含具有 `cognito:`或 `custom:`字首的宣告，以及具有常值 `cognito`或 的宣告名稱`custom`，則具有 [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) 的授權請求會失敗，並顯示 `ValidationException`。 如需映射宣告的詳細資訊，請參閱 [將 Amazon Cognito 字符映射至結構描述](cognito-map-token-to-schema.md)。如需 Amazon Cognito 使用者授權的詳細資訊，請參閱《[Amazon Cognito 開發人員指南》中的使用 Amazon 驗證許可授權](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)。 *Amazon Cognito * **Topics** + [建立 Amazon Verified Permissions Amazon Cognito 身分來源](cognito-create.md) + [編輯 Amazon Verified Permissions Amazon Cognito 身分來源](cognito-edit.md) + [將 Amazon Cognito 字符映射至結構描述](cognito-map-token-to-schema.md) + [的用戶端和對象驗證 Amazon Cognito](cognito-validation.md) # 建立 Amazon Verified Permissions Amazon Cognito 身分來源 下列程序會將身分來源新增至現有的政策存放區。 您也可以在 Verified Permissions 主控台中[建立新的政策存放區時建立](policy-stores-create.md)身分來源。在此程序中，您可以將身分來源字符中的宣告自動匯入實體屬性。選擇**引導式設定**或使用 ** API 閘道 和身分提供者設定**選項。這些選項也會建立初始政策。 **注意** 除非您已建立政策存放區，否則左側導覽窗格中無法使用**身分來源**。您建立的身分來源與目前的政策存放區相關聯。 當您在 中建立具有 [create-identity-source](https://docs.aws.amazon.com/cli/latest/reference/verifiedpermissions/create-identity-source.html) 的身分來源， AWS CLI 或在 Verified Permissions API 中建立 [CreateIdentitySource](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_CreateIdentitySource.html) 時，可以排除委託人實體類型。不過，空白實體類型會建立實體類型為 的身分來源`AWS::Cognito`。此實體名稱與政策存放區結構描述不相容。若要將 Amazon Cognito 身分與您的政策存放區結構描述整合，您必須將委託人實體類型設定為支援的政策存放區實體。 ------ #### [ AWS 管理主控台 ] **建立 Amazon Cognito 使用者集區身分來源** 1. 開啟 [Verified Permissions 主控台](https://console.aws.amazon.com/verifiedpermissions/)。選擇您的政策存放區。 1. 在左側導覽窗格中，選擇**身分來源**。 1. 選擇**建立身分來源**。 1. 在 **Cognito 使用者集區詳細資訊**中，選取 ， AWS 區域 然後輸入身分來源**的使用者集區 ID**。 1. 在**委託人組態**中，針對**委託人類型**，從此來源選擇委託人的實體類型。來自已連線 Amazon Cognito 使用者集區的身分將對應至選取的委託人類型。 1. 在**群組組態**中，如果您想要對應使用者集區`cognito:groups`宣告，請選取**使用 Cognito 群組**。選擇做為委託人類型父項的實體類型。 1. 在**用戶端應用程式驗證**中，選擇是否要驗證用戶端應用程式 IDs。 + 若要驗證用戶端應用程式 IDs，請選擇**僅接受具有相符用戶端應用程式 IDs字符**。為每個要驗證的**用戶端應用程式 ID 選擇新增**用戶端應用程式 ID。若要移除已新增的用戶端應用程式 ID，請選擇用戶端應用程式 ID 旁的**移除**。 + 如果您不想**驗證用戶端應用程式 IDs**，請選擇不要驗證用戶端應用程式 IDs。 1. 選擇**建立身分來源**。 1. （選用） 如果您的政策存放區有結構描述，在您可以參考從 Cedar 政策中的身分或存取權杖擷取的屬性之前，您必須先更新結構描述，讓 Cedar 了解您的身分來源建立的主體類型。除了結構描述之外，還必須包含您要在 Cedar 政策中參考的屬性。如需將 Amazon Cognito 字符屬性映射至 Cedar 主體屬性的詳細資訊，請參閱 [將 Amazon Cognito 字符映射至結構描述](cognito-map-token-to-schema.md)。 **注意** 當您建立 [API 連結政策存放](policy-stores-api-userpool.md)區，或在建立政策存放區時使用**設定 API 閘道 和身分提供者**時，Verified Permissions 會查詢您的使用者集區以取得使用者屬性，並建立結構描述，其中您的主體類型會填入使用者集區屬性。 1. 建立使用字符資訊進行授權決策的政策。如需詳細資訊，請參閱[建立 Amazon Verified Permissions 靜態政策](policies-create.md)。 現在您已建立身分來源、更新結構描述和建立政策，請使用 `IsAuthorizedWithToken`讓 Verified Permissions 進行授權決策。如需詳細資訊，請參閱《*Amazon Verified Permissions API 參考指南*》中的 [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)。 ------ #### [ AWS CLI ] **建立 Amazon Cognito 使用者集區身分來源** 您可以使用 [CreateIdentitySource](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_CreateIdentitySource.html) 操作來建立身分來源。下列範例會建立可從 Amazon Cognito 使用者集區存取已驗證身分的身分來源。 1. 建立包含下列 Amazon Cognito 使用者集區詳細資訊`config.txt`的檔案，以供 `create-identity-source`命令中的 `--configuration` 參數使用。 ``` { "cognitoUserPoolConfiguration": { "userPoolArn": "arn:aws:cognito-idp:us-west-2:123456789012:userpool/us-west-2_1a2b3c4d5", "clientIds":["a1b2c3d4e5f6g7h8i9j0kalbmc"], "groupConfiguration": { "groupEntityType": "MyCorp::UserGroup" } } } ``` 1. 執行下列命令來建立 Amazon Cognito 身分來源。 ``` $ aws verifiedpermissions create-identity-source \ --configuration file://config.txt \ --principal-entity-type "User" \ --policy-store-id 123456789012 { "createdDate": "2023-05-19T20:30:28.214829+00:00", "identitySourceId": "ISEXAMPLEabcdefg111111", "lastUpdatedDate": "2023-05-19T20:30:28.214829+00:00", "policyStoreId": "PSEXAMPLEabcdefg111111" } ``` 1. （選用） 如果您的政策存放區有結構描述，在您可以參考從 Cedar 政策中的身分或存取權杖擷取的屬性之前，您必須先更新結構描述，讓 Cedar 了解您的身分來源建立的主體類型。除了結構描述之外，還必須包含您要在 Cedar 政策中參考的屬性。如需將 Amazon Cognito 字符屬性映射至 Cedar 主體屬性的詳細資訊，請參閱 [將 Amazon Cognito 字符映射至結構描述](cognito-map-token-to-schema.md)。 **注意** 當您建立 [API 連結政策存放](policy-stores-api-userpool.md)區，或在建立政策存放區時使用**設定 API 閘道 和身分提供者**時，Verified Permissions 會查詢您的使用者集區是否有使用者屬性，並建立結構描述，其中您的主體類型會填入使用者集區屬性。 1. 建立使用字符資訊進行授權決策的政策。如需詳細資訊，請參閱[建立 Amazon Verified Permissions 靜態政策](policies-create.md)。 現在您已建立身分來源、更新結構描述和建立政策，請使用 `IsAuthorizedWithToken`讓 Verified Permissions 進行授權決策。如需詳細資訊，請參閱《*Amazon Verified Permissions API 參考指南*》中的 [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)。 ------ 如需在 Verified Permissions 中使用已驗證使用者的 Amazon Cognito 存取和身分字符的詳細資訊，請參閱《Amazon *Amazon Cognito * [Permissions 授權](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)。 # 編輯 Amazon Verified Permissions Amazon Cognito 身分來源 您可以在建立身分來源之後編輯其某些參數。您無法變更身分來源的類型，您必須刪除身分來源並建立新的來源，才能從 切換 Amazon Cognito 到 OIDC 或 OIDC Amazon Cognito。如果您的政策存放區結構描述符合身分來源屬性，請注意，您必須分別更新結構描述，以反映您對身分來源所做的變更。 ------ #### [ AWS 管理主控台 ] **更新 Amazon Cognito 身分來源** 1. 開啟 [Verified Permissions 主控台](https://console.aws.amazon.com/verifiedpermissions/)。選擇您的政策存放區。 1. 在左側導覽窗格中，選擇**身分來源**。 1. 選擇要編輯的身分來源 ID。 1. 選擇**編輯**。 1. 在 **Cognito 使用者集區詳細資訊**中，選取 AWS 區域 並輸入身分來源**的使用者集區 ID**。 1. 在**主體詳細資訊**中，您可以更新身分來源的**主體類型**。來自已連線 Amazon Cognito 使用者集區的身分將對應至選取的委託人類型。 1. 在**群組組態**中，如果您想要對應使用者集區`cognito:groups`宣告，請選取**使用 Cognito 群組**。選擇做為委託人類型父項的實體類型。 1. 在**用戶端應用程式驗證**中，選擇是否要驗證用戶端應用程式 IDs。 + 若要驗證用戶端應用程式 IDs，請選擇**僅接受具有相符用戶端應用程式 IDs字符**。為每個要驗證的**用戶端應用程式 ID 選擇新增**用戶端應用程式 ID。若要移除已新增的用戶端應用程式 ID，請選擇用戶端應用程式 ID 旁的**移除**。 + 如果您不想**驗證用戶端應用程式 IDs**，請選擇不要驗證用戶端應用程式 IDs。 1. 選擇**儲存變更**。 1. 如果您變更身分來源的委託人類型，則必須更新結構描述，以正確反映更新的委託人類型。 您可以選擇身分來源旁的選項按鈕，然後選擇**刪除身分來源，以刪除身分來源**。在文字方塊`delete`中輸入 ，然後選擇**刪除身分來源**以確認刪除身分來源。 ------ #### [ AWS CLI ] **更新 Amazon Cognito 身分來源** 您可以使用 [UpdateIdentitySource](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_UpdateIdentitySource.html) 操作來更新身分來源。下列範例會更新指定的身分來源，以使用不同的 Amazon Cognito 使用者集區。 1. 建立包含下列 Amazon Cognito 使用者集區詳細資訊`config.txt`的檔案，以供 `update-identity-source`命令中的 `--configuration` 參數使用。 ``` { "cognitoUserPoolConfiguration": { "userPoolArn": "arn:aws:cognito-idp:us-west-2:123456789012:userpool/us-west-2_1a2b3c4d5", "clientIds":["a1b2c3d4e5f6g7h8i9j0kalbmc"], "groupConfiguration": { "groupEntityType": "MyCorp::UserGroup" } } } ``` 1. 執行下列命令來更新 Amazon Cognito 身分來源。 ``` $ aws verifiedpermissions update-identity-source \ --update-configuration file://config.txt \ --policy-store-id 123456789012 { "createdDate": "2023-05-19T20:30:28.214829+00:00", "identitySourceId": "ISEXAMPLEabcdefg111111", "lastUpdatedDate": "2023-05-19T20:30:28.214829+00:00", "policyStoreId": "PSEXAMPLEabcdefg111111" } ``` **注意** 如果您變更身分來源的委託人類型，則必須更新結構描述，以正確反映更新的委託人類型。 ------ # 將 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)。 # 的用戶端和對象驗證 Amazon Cognito 當您將身分來源新增至政策存放區時，Verified Permissions 具有組態選項，可驗證 ID 和存取權杖是否如預期般使用。此驗證會在處理 `IsAuthorizedWithToken`和 `BatchIsAuthorizedWithToken` API 請求時發生。ID 和存取字符，以及 Amazon Cognito 和 OIDC 身分來源的行為有所不同。使用 Amazon Cognito 使用者集區提供者，Verified Permissions 可以驗證 ID 和存取權杖中的用戶端 ID。使用 OIDC 供應商，Verified Permissions 可以驗證 ID 字符中的用戶端 ID，以及存取字符中的對象。 *用戶端 ID* 是與您應用程式使用的身分提供者執行個體相關聯的識別符，例如 `1example23456789`。*對象*是與存取字符的預期*依賴方*或目的地相關聯的 URL 路徑，例如 `https://mytoken.example.com`。使用存取權杖時，`aud`宣告一律會與對象建立關聯。 Amazon Cognito ID 字符具有包含[應用程式用戶端](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) ID 的`aud`宣告。存取字符的`client_id`宣告也包含應用程式用戶端 ID。 當您在身分來源中輸入一或多個**用戶端應用程式驗證**值時，Verified Permissions 會將此應用程式用戶端 IDs 清單與 ID 字符`aud`宣告或存取字符`client_id`宣告進行比較。Verified Permissions 不會驗證 Amazon Cognito 身分來源的依賴方對象 URL。 ## JWTs的用戶端授權 您可能想要在應用程式中處理 JSON Web 字符，並在不使用政策存放區身分來源的情況下將其宣告傳遞給 Verified Permissions。您可以從 JSON Web Token (JWT) 擷取實體屬性，並將其剖析為驗證許可。 此範例示範如何使用 JWT.1 從應用程式呼叫 Verified Permissions。 ``` async function authorizeUsingJwtToken(jwtToken) { const payload = await verifier.verify(jwtToken); let principalEntity = { entityType: "PhotoFlash::User", // the application needs to fill in the relevant user type entityId: payload["sub"], // the application need to use the claim that represents the user-id }; let resourceEntity = { entityType: "PhotoFlash::Photo", //the application needs to fill in the relevant resource type entityId: "jane_photo_123.jpg", // the application needs to fill in the relevant resource id }; let action = { actionType: "PhotoFlash::Action", //the application needs to fill in the relevant action id actionId: "GetPhoto", //the application needs to fill in the relevant action type }; let entities = { entityList: [], }; entities.entityList.push(...getUserEntitiesFromToken(payload)); let policyStoreId = "PSEXAMPLEabcdefg111111"; // set your own policy store id const authResult = await client .isAuthorized({ policyStoreId: policyStoreId, principal: principalEntity, resource: resourceEntity, action: action, entities, }) .promise(); return authResult; } function getUserEntitiesFromToken(payload) { let attributes = {}; let claimsNotPassedInEntities = ['aud', 'sub', 'exp', 'jti', 'iss']; Object.entries(payload).forEach(([key, value]) => { if (claimsNotPassedInEntities.includes(key)) { return; } if (Array.isArray(value)) { var attibuteItem = []; value.forEach((item) => { attibuteItem.push({ string: item, }); }); attributes[key] = { set: attibuteItem, }; } else if (typeof value === 'string') { attributes[key] = { string: value, } } else if (typeof value === 'bigint' || typeof value ==='number') { attributes[key] = { long: value, } } else if (typeof value === 'boolean') { attributes[key] = { boolean: value, } } }); let entityItem = { attributes: attributes, identifier: { entityType: "PhotoFlash::User", entityId: payload["sub"], // the application needs to use the claim that represents the user-id } }; return [entityItem]; } ``` 1 此程式碼範例使用 [aws-jwt-verify](https://github.com/awslabs/aws-jwt-verify) 程式庫來驗證由 OIDC 相容 IdPs 簽署的 JWTs。