How do I configure an SSO user to access my Amazon EKS cluster?

Resolution

Prerequisites

• IAM Identity Center must be turned on and configured
• The SSO user must be associated with the AWS account that contains the EKS cluster
• The EKS cluster must support Access Entries (platform version eks.2 or later)

To configure an SSO user to access your Amazon EKS cluster, complete the following steps:

Configure AWS CLI for SSO authentication

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Configure the AWS CLI to use SSO authentication so the SSO user can authenticate and assume an AWS Identity and Access Management (IAM) role.

For more information about configuring the AWS CLI with IAM Identity Center, see Integrating AWS CLI with IAM Identity Center.

Configure kubectl to use the SSO profile

To configure kubectl to use your SSO profile, run the following update-kubeconfig AWS CLI command:

aws eks update-kubeconfig --name your-cluster-name --profile your-sso-profile

Note: Replace your-cluster-name with your EKS cluster name. Replace your-sso-profile with your SSO profile name.

Verify the cluster authentication mode

To verify the cluster authentication mode, run the following describe-cluster AWS CLI command:

aws eks describe-cluster --name your-cluster-name --query "cluster.accessConfig.authenticationMode" --profile your-sso-profile

Note: Replace your-cluster-name with your EKS cluster name. Replace your-sso-profile with your SSO profile name.

If the output shows API or API_AND_CONFIG_MAP, then Access Entries are turned on. If the output shows CONFIG_MAP, then only the aws-auth ConfigMap method is available.

Use Access Entries to configure access

Choose one of the following permission levels:

Grant cluster-wide admin permissions

Complete the following steps:

1. Open the Amazon EKS console.
2. In the navigation pane, choose Clusters.
3. Select your cluster.
4. Choose the Access tab.
5. In the Access entries section, choose Create access entry.
6. For IAM principal ARN, enter your SSO role ARN without the path component.
7. For Type, choose Standard.
8. Choose Next.
9. For Policy name, choose AmazonEKSClusterAdminPolicy.
10. For Access scope, choose Cluster.
11. Choose Next, then choose Create.

Grant namespace-specific permissions

Complete the following steps:

1. Open the Amazon EKS console.
2. In the navigation pane, choose Clusters.
3. Select your cluster.
4. Choose the Access tab.
5. In the Access entries section, choose Create access entry.
6. For IAM principal ARN, enter your SSO role ARN without the path component.
7. For Type, choose Standard.
8. Choose Next.
9. For Policy name, choose AmazonEKSAdminViewPolicy or AmazonEKSEditPolicy based on your requirements.
10. For Access scope, choose Namespace.
11. For Namespace, enter your namespace name.
12. Choose Next, then choose Create.

For more information about Access Entries, see Grant IAM users access to Kubernetes with EKS access entries.

Use aws-auth ConfigMap to configure access

Important: When you use aws-auth with IAM Identity Center, use the IAM role ARN without the path component. For example, if your role ARN is arn:aws:iam::123456789012:role/aws-reserved/sso.amazonaws.com/us-east-1/AWSReservedSSO_AdministratorAccess_1234567890abcdef, remove the path to use arn:aws:iam::123456789012:role/AWSReservedSSO_AdministratorAccess_1234567890abcdef.

If your cluster doesn't support Access Entries or you prefer to use the aws-auth ConfigMap method, complete the following steps:

Grant cluster-wide admin permissions

Create a YAML file with the following configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    - rolearn: arn:aws:iam::123456789012:role/AWSReservedSSO_AdministratorAccess_1234567890abcdef
      username: sso-admin-user
      groups:
        - system:masters

Note: Replace the rolearn value with your SSO role ARN without the path component. Replace sso-admin-user with your preferred username.

Apply the configuration:

kubectl apply -f aws-auth-configmap.yaml

Grant namespace-specific permissions

Create a Role and RoleBinding for namespace-specific access:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: sso-user-role
  namespace: your-namespace
rules:
- apiGroups: [""]
  resources: ["pods", "services", "configmaps"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: sso-user-rolebinding
  namespace: your-namespace
subjects:
- kind: User
  name: sso-user
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: sso-user-role
  apiGroup: rbac.authorization.k8s.io

Note: Replace your-namespace with your namespace name. Replace sso-user with the username you specified in the aws-auth ConfigMap.

Apply the configuration:

kubectl apply -f role-rolebinding.yaml

Update the aws-auth ConfigMap to map the SSO role to the username:

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    - rolearn: arn:aws:iam::123456789012:role/AWSReservedSSO_AdministratorAccess_1234567890abcdef
      username: sso-user

Note: Replace the rolearn value with your SSO role ARN without the path component.

Apply the configuration:

kubectl apply -f aws-auth-configmap.yaml

For more information about the aws-auth ConfigMap, see Grant IAM users access to Kubernetes with a ConfigMap.

Verify access

To verify the SSO user can access the cluster, run the following command:

kubectl get nodes

If the command returns a list of nodes, then the SSO user has successfully authenticated to the cluster.

Related information

Cluster access management