Referencing permission sets in resource policies, Amazon EKS Cluster config maps, and AWS KMS key policies - AWS IAM Identity Center
Recommendations to avoid access disruptionsCustom trust policy example

Referencing permission sets in resource policies, Amazon EKS Cluster config maps, and AWS KMS key policies

When you assign a permission set to an AWS 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:iam::aws-account-ID:role/aws-reserved/sso.amazonaws.com/aws-region/AWSReservedSSO_permission-set-name_unique-suffix

If your identity source in IAM Identity Center is hosted in us-east-1, there is no aws-region in the ARN. The complete name and ARN for the role use the following format:

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

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

Name ARN
AWSReservedSSO_DatabaseAdministrator_1234567890abcdef arn:aws: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 AWS 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: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) clusters when you use the aws-auth ConfigMap for cluster access.

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

Note

We recommend that you use Amazon EKS access entries to manage access to your Amazon EKS clusters. This allows you to use IAM permissions to manage the principals that have access to an Amazon EKS cluster. By using Amazon EKS access entries, you can use an IAM principal with Amazon EKS permissions to regain access to a cluster without contacting AWS Support.

Although you can update resource-based policies for most AWS 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 AWS KMS if the ARN changes. For Amazon EKS, the backup IAM role must exist in the aws-auth ConfigMap. For AWS KMS, it must exist in your key policies. If you don’t have a backup IAM role with permissions to update the aws-auth ConfigMap or the AWS KMS key policy, contact AWS Support to regain access to those resources.

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 AWS accounts that contain the roles that you reference in the aws-auth ConfigMap for Amazon EKS, key policies in AWS KMS, or resource-based policies for other AWS services.

    For example, if you create an EKSAccess permission set and reference the corresponding role ARN from AWS 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 clusters that use aws-auth ConfigMap and AWS 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 AWS 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 AWS 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 AWS KMS key policy. The next section provides an example of how you can create a trust policy for a role that's 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's created in IAM. The key elements of this policy include:

  • The Principal element of this trust policy specifies an AWS account principal. In this policy, principals in the AWS account 111122223333 with sts:AssumeRole permissions can assume the role that's 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: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 allows 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:iam::111122223333:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "ArnLike": {
          "aws:PrincipalArn": "arn:aws: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, AWS KMS keys, or other AWS resources if a permission set or all assignments to the permission set are accidentally deleted and re-created.