Referencing permission sets in resource policies, Amazon EKS, and Amazon KMS - Amazon IAM Identity Center
Recommendations to avoid access disruptionsCustom trust policy example
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Referencing permission sets in resource policies, Amazon EKS, and Amazon KMS

When you assign a permission set to an Amazon account, IAM Identity Center creates a role with a name that begins with AWSReservedSSO_.

The complete name and Amazon Resource Name (ARN) for the role use the following format:

Name ARN
AWSReservedSSO_permission-set-name_unique-suffix arn:aws-cn:iam::aws-account-ID:role/aws-reserved/sso.amazonaws.com/aws-region/AWSReservedSSO_permission-set-name_unique-suffix

For example, if you create a permission set that grants Amazon account access to database administrators, a corresponding role is created with the following name and ARN:

Name ARN
AWSReservedSSO_DatabaseAdministrator_1234567890abcdef arn:aws-cn:iam::111122223333:role/aws-reserved/sso.amazonaws.com/eu-west-2/AWSReservedSSO_DatabaseAdministrator_1234567890abcdef

If you delete all assignments to this permission set in the Amazon account, the corresponding role that IAM Identity Center created is also deleted. If you make a new assignment to the same permission set later, IAM Identity Center creates a new role for the permission set. The name and ARN of the new role include a different, unique suffix. In this example, the unique suffix is abcdef0123456789.

Name ARN
AWSReservedSSO_DatabaseAdministrator_abcdef0123456789 arn:aws-cn:iam::111122223333:role/aws-reserved/sso.amazonaws.com/eu-west-2/AWSReservedSSO_DatabaseAdministrator_abcdef0123456789

The suffix change in the new name and ARN for the role will cause any policies that reference the original name and ARN to be out-of-date, which disrupts access for individuals who use the corresponding permission set. For example, a change in the ARN for the role will disrupt access for users of the permission set if the original ARN is referenced in the following configurations:

  • In the aws-auth ConfigMap file for Amazon Elastic Kubernetes Service (Amazon EKS)

  • In a resource-based policy for an Amazon Key Management Service (Amazon KMS) key. This policy is also referred to as a key policy.

Although you can update resource-based policies for most Amazon services to reference a new ARN for a role that corresponds to a permission set, you must have a backup role that you create in IAM for Amazon EKS and Amazon KMS if the ARN changes. For Amazon EKS, the backup IAM role must exist in the aws-auth ConfigMap. For Amazon KMS, it must exist in your key policies. If you don’t have a backup IAM role in either case, you must contact Amazon Web Services Support.

Recommendations to avoid access disruptions

To avoid access disruptions due to changes in the ARN for a role that corresponds to a permission set, we recommend that you do the following.

  • Maintain at least one permission set assignment.

    Maintain this assignment in the Amazon accounts that contain the roles that you reference in the aws-auth ConfigMap for Amazon EKS, key policies in Amazon KMS, or resource-based policies for other Amazon Web Services.

    For example, if you create an EKSAccess permission set and reference the corresponding role ARN from Amazon account 111122223333, then permanently assign an administrative group to the permission set in that account. Because the assignment is permanent, IAM Identity Center won’t delete the corresponding role, which eliminates the renaming risk. The administrative group will always have access without the risk of privilege escalation.

  • For Amazon EKS and Amazon KMS: Include a role created in IAM.

    If you reference role ARNs for permission sets in an aws-auth ConfigMap for Amazon EKS cluster or in key policies for Amazon KMS keys, we recommend that you also include at least one role that you create in IAM. The role must allow you to access the Amazon EKS cluster or manage the Amazon KMS key policy. The permission set must be able to assume this role. That way, if the role ARN for a permission set changes, you can update the reference to the ARN in the aws-auth ConfigMap or Amazon KMS key policy. The next section provides an example of how you can create a trust policy for a role that is created in IAM. The role can be assumed only by an AdministratorAccess permission set.

Custom trust policy example

Following is an example of a custom trust policy that provides an AdministratorAccess permission set with access to a role that is created in IAM. The key elements of this policy include:

  • The Principal element of this trust policy specifies an Amazon account principal. In this policy, principals in the Amazon account 111122223333 with sts:AssumeRole permissions can assume the role that is created in IAM.

  • The Condition element of this trust policy specifies additional requirements for principals that can assume the role created in IAM. In this policy, the permission set with the following role ARN can assume the role.

    arn:aws-cn:iam::111122223333:role/aws-reserved/sso.amazonaws.com/eu-west-2/AWSReservedSSO_AdministratorAccess_*"
    Note

    The Condition element includes the ArnLike condition operator and uses a wildcard at the end of the permission set role ARN, rather than a unique suffix. This means that the policy will allow the permission set to assume the role created in IAM even if the role ARN for the permission set changes. 

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws-cn:iam::111122223333:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "ArnLike": {
          "aws:PrincipalArn": "arn:aws-cn:iam::111122223333:role/aws-reserved/sso.amazonaws.com/eu-west-2/AWSReservedSSO_AdministratorAccess_*"
        }
      }
    }
  ]
}

    Including a role that you create in IAM in such a policy will provide you with emergency access to your Amazon EKS clusters, Amazon KMS keys, or other Amazon resources if a permission set or all assignments to the permission set are accidentally deleted and re-created.