本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用以角色為基礎的存取控制 Amazon Cognito 身分集區會為您的已驗證使用者指派一組臨時、有限權限的登入資料，以存取您的 AWS 資源。每個使用者的許可都是透過您建立的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)來控制。您也可以定義規則，以依據使用者 ID 權杖中的宣告，為每個使用者選擇角色。您可以為已驗證的使用者定義預設角色。您也可以為未驗證的訪客使用者，另外定義有限許可的 IAM 角色。 ## 建立角色以進行角色映射 為每個角色新增適當的信任政策是很重要的，這樣才能讓 Amazon Cognito 針對身分集區中的已驗證使用者來採用信任政策。以下是這種信任政策的範例： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Federated": "cognito-identity.amazonaws.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "cognito-identity.amazonaws.com:aud": "us-east-1:12345678-corner-cafe-123456790ab" }, "ForAnyValue:StringLike": { "cognito-identity.amazonaws.com:amr": "authenticated" } } } ] } ``` ------ 此政策可讓來自 `cognito-identity.amazonaws.com`(OpenID Connect 權杖的發行者) 的聯合身分使用者擔任這個角色。此外，政策會限制權杖的 `aud`(在此案例中為身分集區 ID) 來配合身分集區。最後，政策會指定權杖 (由 Amazon Cognito `GetOpenIdToken` API 動作發出) 之多值 `amr` 宣告的其中一個陣列成員包含值 `authenticated`。 ## 授予傳送角色許可 若要讓使用者設定角色，使擁有的許可超過使用者對身分集區現有的許可，您可以授與該使用者 `iam:PassRole` 許可，以將角色傳遞至 `set-identity-pool-roles` API。例如，如果使用者無法寫入 Amazon S3，但是使用者在身分集區上設定的 IAM 角色會授予對 Amazon S3 的寫入許可，則除非將 `iam:PassRole` 許可授予至此角色，否則該使用者無法設定此角色。下列政策範例顯示如何允許 `iam:PassRole` 許可。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "Stmt1", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::123456789012:role/myS3WriteAccessRole" ] } ] } ``` ------ 在此政策範例中，已將 `iam:PassRole` 許可授與 `myS3WriteAccessRole` 角色。該角色是使用角色的 Amazon Resource Name (ARN) 來指定。您也必須將此政策附加至使用者。如需詳細資訊，請參閱[處理受管政策的相關文章](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html)。 **注意** Lambda 函數使用的是資源型政策，即是政策直接連接至 Lambda 函數本身。在建立叫用 Lambda 函數的規則時，並不會傳送角色，因此建立該規則的使用者不需擁有 `iam:PassRole` 許可。如需 Lambda 函數授權的詳細資訊，請參閱[管理許可：使用 Lambda 函數政策](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy)。 ## 使用權杖來指派角色給使用者 針對透過 Amazon Cognito 使用者集區登入的使用者，可以在由使用者集區指派的 ID 權杖中傳遞角色。這些角色會出現在 ID 權杖的下列宣告中： + `cognito:preferred_role`宣告是角色 ARN。 + `cognito:roles`宣告以逗號分隔的字串，其中包含一組允許的角色 ARN。 宣告設定如下： + `cognito:preferred_role`宣告設定為具有最高 (最小) `Precedence` 值的群組中的角色。如果只有一個允許的角色，則 `cognito:preferred_role`會設定為該角色。如果有多個角色，而沒有任何角色具有最高優先順序，則不會設定此宣告。 + 如果至少有一個角色，就會設定 `cognito:roles`宣告。 使用權杖來指派角色時，如果有多個角色可以指派給使用者，Amazon Cognito 身分集區 (聯合身分) 會依下列方式來選擇角色： + 如果已設定的 [GetCredentialsForIdentity](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_GetCredentialsForIdentity.html) `CustomRoleArn` 參數符合 `cognito:roles` 宣告中的角色，則使用此參數。如果此參數不符合 `cognito:roles`中的角色，則拒絕存取。 + 如果已設定 `cognito:preferred_role`宣告，則加以使用。 + 如果未設定 `cognito:preferred_role` 宣告、已設定 `cognito:roles` 宣告，且未在 `GetCredentialsForIdentity` 的呼叫中指定 `CustomRoleArn` ，則會使用主控台中的 **Role resolution** (角色解析) 設定或是 `AmbiguousRoleResolution` 欄位 (在 [SetIdentityPoolRoles](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_SetIdentityPoolRoles.html) API 的 `RoleMappings` 參數中) 來判斷所要指派的角色。 ## 使用以規則為基礎的映射來指派角色給使用者 規則可讓您將宣告從身分提供者權杖對應至 IAM 角色。 每個規則都會指定權杖宣告 (如來自 Amazon Cognito 使用者集區之 ID 權杖的使用者屬性)、相符類型、值及 IAM 角色。相符類型可以是 `Equals`、`NotEqual`、`StartsWith` 或 `Contains`。如果使用者有符合宣告的值，則當使用者取得登入資料時，即可擔任該角色。例如，您可以建立一個規則，將特定 IAM 角色指派給 `custom:dept` 自訂屬性值為 `Sales` 的使用者。 **注意** 在規則設定中，自訂屬性需要 `custom:`字首來將其與標準屬性區分。 規則會依序評估，並且會使用第一個相符規則的 IAM 角色，除非是指定 `CustomRoleArn` 來覆寫該順序。如需 Amazon Cognito 使用者集區中的使用者屬性詳細資訊，請參閱[使用使用者屬性](user-pool-settings-attributes.md)。 您可以在身分集區 (聯合身分) 主控台中，針對身分驗證供應商設定多個規則。規則會依序套用。您可以曳規則來變更順序。第一個相符的規則優先。如果相符類型為 `NotEqual`，且宣告不存在，則不會評估規則。如果沒有規則相符，則會將 **角色解析** 設定套用至 **使用預設的已驗證角色** 或 **拒絕**。 在 API 和 CLI 中，您可以指定 `AmbiguousRoleResolution`RoleMapping[ 類型的 ](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_RoleMapping.html) 欄位中 (指定在 `RoleMappings`SetIdentityPoolRoles[ API 的 ](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_SetIdentityPoolRoles.html) 參數中) 沒有規則相符時，所要指派的角色。 若要在 Amazon Cognito 主控台中將規則型映射新增至身分提供者，請新增或更新 IdP，然後選取在**角色選擇下選擇具有規則****的角色**。從那裡，您可以新增將提供者宣告映射至 IAM 角色的規則。 您可以使用 [RoleMapping](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_RoleMapping.html) 類型的 `RulesConfiguration` 欄位，在 AWS CLI 或 API 中為身分提供者設定規則型映射。您可以在 [SetIdentityPoolRoles](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_SetIdentityPoolRoles.html) API 的 `RoleMappings` 參數中指定此欄位。 例如，下列 AWS CLI 命令新增規則，將角色指派給您 Sacramento 位置中經過 OIDC IdP 身分驗證`arn:aws:iam::123456789012:role/Sacramento_team_S3_admin`的使用者`arn:aws:iam::123456789012:oidc-provider/myOIDCIdP`： ``` aws cognito-identity set-identity-pool-roles --region us-east-1 --cli-input-json file://role-mapping.json ``` **`role-mapping.json` 的內容**： ``` { "IdentityPoolId": "us-east-1:12345678-corner-cafe-123456790ab", "Roles": { "authenticated": "arn:aws:iam::123456789012:role/myS3WriteAccessRole", "unauthenticated": "arn:aws:iam::123456789012:role/myS3ReadAccessRole" }, "RoleMappings": { "arn:aws:iam::123456789012:oidc-provider/myOIDCIdP": { "Type": "Rules", "AmbiguousRoleResolution": "AuthenticatedRole", "RulesConfiguration": { "Rules": [ { "Claim": "locale", "MatchType": "Equals", "Value": "Sacramento", "RoleARN": "arn:aws:iam::123456789012:role/Sacramento_team_S3_admin" } ] } } } } ``` 針對每個使用者集區，或是您為身分集區設定的其他身分驗證供應商，最多可以建立 25 個規則。此限制不可調整。如需詳細資訊，請參閱 [Amazon Cognito 中的配額](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html)。 ## 要用在以規則為基礎之映射中的宣告 **Amazon Cognito** Amazon Cognito ID 權杖是以 JSON Web 權杖 (JWT) 表示。權杖中包含已驗證使用者身分的相關宣告，例如 `name`、`family_name` 和 `phone_number`。如需標準宣告的詳細資訊，請參閱 [OpenID Connect 規格](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)。除了標準宣告，Amazon Cognito 還有下列專屬的其他宣告： + `cognito:groups` + `cognito:roles` + `cognito:preferred_role` **Amazon** 下列宣告及這些宣告的可能值可用於 Login with Amazon： + `iss`：www.amazon.com + `aud`：應用程式 ID + `sub`：來自 Login with Amazon 權杖的 `sub` **Facebook** 下列宣告及這些宣告的可能值可用於 Facebook： + `iss`：graph.facebook.com + `aud`：應用程式 ID + `sub`：來自 Facebook 權杖的 `sub` **Google** Google 權杖包含來自 [OpenID Connect 規格](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)的標準宣告。OpenID 權杖中的所有宣告都可用於以規則為基礎的對應。請參閱 Google 的 [OpenID Connect](https://developers.google.com/identity/protocols/OpenIDConnect) 網站，以了解來自 Google 權杖的可用宣告。 **Apple** Apple 權杖包含來自 [OpenID Connect 規格](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)的標準宣告。請參閱 Apple 文件中的 [Authenticating Users with Sign in with Apple](https://developer.apple.com/documentation/signinwithapple/authenticating-users-with-sign-in-with-apple)，以進一步了解來自 Apple 權杖的可用宣告。Apple 的權杖並非一定會包含 `email`。 **OpenID** OpenID 權杖中的所有要求都適用於以規則為基礎的對應。如需標準宣告的詳細資訊，請參閱 [OpenID Connect 規格](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)。請參閱您的 OpenID 供應商說明文件，以了解任何可用的其他宣告。 **SAML** 宣告是從收到的 SAML 聲明剖析而來。SAML 聲明中所有可用的宣告，都可以用在以規則為基礎的對應中。 ## 以角色為基礎的存取控制最佳實務 **重要** 如果最終使用者可以修改您對應至角色的宣告，則任何最終使用者都可以擔任您的角色，並依情況設定政策。請只將無法由最終使用者直接設定的宣告對應至具有更高許可的角色。在 Amazon Cognito 使用者集區中，您可以依每個應用程式來設定每個使用者屬性的讀取和寫入許可。 **重要** 如果您為 Amazon Cognito 使用者集區中的群組設定角色，將會透過使用者的 ID 權杖來剖析這些角色。若要使用這些角色，身分集區的已驗證角色選項必須設定 **Choose role from token (從權杖選擇角色)**。 您可以使用主控台中的 **Role resolution** (角色解析) 設定，以及 `RoleMappings`SetIdentityPoolRoles[ API 的 ](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_SetIdentityPoolRoles.html) 參數，來指定當無法從權杖判定正確角色時的預設行為。