Higherpass

Connecting Your EKS Cluster to AWS SSO

Introduction

In today’s complex cloud environments, managing access to Kubernetes clusters can be challenging. This guide will walk you through the process of integrating your EKS cluster with SSO and EC2 Instance Profiles, ensuring your team can access Kubernetes resources efficiently.

By default, only the IAM principal that created the cluster has access to view the Kubernetes resources via the AWS console or CLI. This causes significant limitations in visibility for team members or administrators who use instance roles to access AWS resources and use eksctl. When going into the AWS console with an SSO credential, there is no inherent cluster access, creating a critical access management barrier.

While this guide focuses on SSO integration, the patterns and principles discussed can be equally applied to other IAM roles, providing a flexible framework for managing Kubernetes access across different authentication methods and use cases.

The integration of EKS with IAM roles addresses these challenges by:

  1. Expanding Access Control: Enabling broader team access to Kubernetes resources beyond the cluster creator
  2. Simplifying Authentication: Providing a unified method for accessing Kubernetes clusters through IAM credentials
  3. Enhancing Visibility: Allowing team members using various IAM roles to view and interact with EKS resources
  4. Streamlining Security: Implementing fine-grained access controls that align with your organization’s identity management strategy

By implementing this approach, you’ll create a more accessible, secure, and manageable Kubernetes environment that breaks down traditional access silos and provides a scalable access management strategy.

Prerequisites

Before starting, ensure you have the following:

Tools and Access

  • AWS CLI installed and configured
  • kubectl installed
  • eksctl installed
  • Access to AWS Management Console
  • An existing EKS cluster

IAM Considerations

  • IAM role with appropriate permissions (SSO or standard IAM role)
  • Understanding of your organization’s IAM strategy
  • Cluster creation IAM principal details

Understanding IAM Role Trust Relationships

IAM role trust relationships are a critical component of secure access management in AWS. A trust relationship defines the conditions under which an IAM role can be assumed, essentially establishing a secure bridge between identity providers and AWS resources.

Key aspects of IAM role trust relationships:

  • Purpose: Determine who can assume a specific IAM role
  • Components:
    • Identity Provider (e.g., AWS SSO, SAML)
    • Principal (user or service attempting to access resources)
    • Target IAM Role with specific permissions

Example trust policy structure:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::ACCOUNT_ID:saml-provider/PROVIDER_NAME"
            },
            "Action": "sts:AssumeRoleWithSAML",
            "Condition": {
                "StringEquals": {
                    "SAML:aud": "https://signin.aws.amazon.com/saml"
                }
            }
        }
    ]
}

In the context of EKS:

  • Trust relationships enable seamless authentication between AWS SSO and your Kubernetes cluster
  • They provide a secure mechanism for mapping external identities to Kubernetes access
  • Allow fine-grained control over who can access your EKS resources

Pro Tip: Always follow the principle of least privilege when configuring trust relationships, granting only the minimum necessary permissions.

  1. Identify the IAM roles that require Kubernetes cluster access
    • SSO roles
    • Service account roles
    • Instance profile roles
  2. Gather the full ARNs for these roles
  3. Confirm the roles have appropriate permissions for Kubernetes interactions

Key Information to Collect

  • EKS Cluster Name
  • AWS Region
  • IAM Role ARNs for access
  • AWS Account ID

Note: While this guide demonstrates SSO integration, the principles can be adapted for various IAM role types, providing flexibility in your access management approach.

Step-by-Step Connection Process

1. Retrieve Cluster Credentials

First, update your kubeconfig to ensure you can interact with the cluster. This step works for both SSO and standard IAM roles:

aws eks get-token --cluster-name YOUR_CLUSTER_NAME --region YOUR_REGION

2. Configure AWS CLI Authentication

Depending on your authentication method, choose the appropriate configuration:

For SSO

aws configure sso

Follow the prompts to:

  • Enter your SSO start URL
  • Select your SSO region
  • Choose the appropriate SSO role
  • Create a profile name

For Standard IAM Roles

aws configure --profile your-role-profile
# Manually enter AWS Access Key ID, Secret Access Key, and region

3. Modify AWS Auth ConfigMap

The aws-auth ConfigMap is crucial for mapping IAM roles to Kubernetes roles. This is a flexible approach that works for multiple IAM role types.

  1. Create an aws-auth.yaml file:
apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    # Node Group Role
    - rolearn: YOUR_NODE_ROLE_ARN
      username: system:node:{{EC2PrivateDNSName}}
      groups:
        - system:bootstrappers
        - system:nodes
    
    # SSO or Additional IAM Role
    - rolearn: YOUR_IAM_ROLE_ARN
      username: sso-or-role-user
      groups:
        - system:masters
    
    # Additional roles can be added here
  1. Apply the ConfigMap:
kubectl apply -f aws-auth.yaml

4. Verify Access

Confirm your access by listing the cluster nodes:

# Use the specific AWS profile if needed
aws eks get-token --cluster-name YOUR_CLUSTER_NAME --region YOUR_REGION | kubectl apply -f -

# Verify access
kubectl get nodes

5. Additional Configurations (Optional)

  • For multiple roles, repeat the mapping process in the aws-auth ConfigMap
  • Use different Kubernetes groups to implement granular access control
  • Consider using Kubernetes RBAC for more fine-grained permissions

Pro Tip: Always follow the principle of least privilege. Avoid adding roles to the system:masters group unless absolutely necessary.

Troubleshooting Tips

Common Access Issues

1. Authentication Failures

  • Symptom: Unable to access Kubernetes resources
  • Checks:
    # Verify AWS CLI configuration
    aws sts get-caller-identity
    # Check kubectl context
    kubectl config current-context
    # Validate AWS token
    aws eks get-token --cluster-name YOUR_CLUSTER_NAME

2. Role Mapping Problems

  • Potential Causes:
    • Incorrect IAM Role ARN in aws-auth ConfigMap
    • Mismatched role trust relationships
    • Insufficient IAM permissions
  • Diagnostic Steps:
    # Verify IAM role ARN
    aws iam get-role --role-name YOUR_ROLE_NAME
    # Check ConfigMap mapping
    kubectl get configmap aws-auth -n kube-system -o yaml

3. Nodegroup and Instance Role Detection

  • Troubleshooting Commands
    :# List EKS nodegroups
    aws eks list-nodegroups --cluster-name YOUR_CLUSTER_NAME # Verify alternative nodegroup detection
    eksctl get nodegroup --cluster YOUR_CLUSTER_NAME
    # Check instance role connectivity
    aws ec2 describe-instances --filters "Name=iam-instance-profile.arn,Values=YOUR_INSTANCE_PROFILE_ARN"

Advanced Diagnostics

IAM Permission Verification

  • Use AWS IAM Access Analyzer to identify potential permission issues
  • Review CloudTrail logs for denied access attempts
  • Implement temporary elevated permissions for debugging

Kubernetes RBAC Debugging

# Check user/group permissions
kubectl auth can-i list pods --as=system:serviceaccount:default:default

# Detailed permission review
kubectl describe clusterroles
kubectl describe clusterrolebindings

Common Pitfalls to Avoid

  • Never use system:masters group indiscriminately
  • Always use the most specific IAM role possible
  • Regularly audit and rotate IAM credentials
  • Implement multi-factor authentication

Logging and Monitoring

  • Enable detailed logging in AWS EKS console
  • Use CloudWatch for monitoring authentication attempts
  • Set up alerts for repeated access failures

Security Considerations

IAM Role Management

  • Principle of Least Privilege: Always assign the minimum necessary permissions
  • Regularly audit and rotate IAM roles
  • Use distinct roles for different access levels and use cases
  • Implement time-bound or just-in-time access where possible

Kubernetes RBAC Best Practices

  • Avoid using system:masters group for routine access
  • Create granular Kubernetes Role and ClusterRole definitions
  • Map IAM roles to specific Kubernetes groups with limited permissions
  • Implement namespace-level access controls

Authentication and Authorization

  • Enable AWS Identity and Access Management (IAM) authenticator
  • Use multi-factor authentication for all IAM roles
  • Implement strong password policies
  • Regularly review and remove unnecessary access credentials

Monitoring and Auditing

  • Enable AWS CloudTrail for comprehensive logging
  • Set up CloudWatch alerts for suspicious access attempts
  • Regularly review authentication and access logs
  • Implement automated compliance checks

Configuration Security

# Example: Restrict ConfigMap modifications
kubectl create rolebinding limited-configmap-access \
  --role=configmap-reader \
  --serviceaccount=default:default

Additional Protective Measures

  • Encrypt sensitive configuration data
  • Use AWS Secrets Manager for credential management
  • Implement network policies to restrict cluster access
  • Regularly update Kubernetes and AWS CLI tools

Pro Tip: Treat your IAM and Kubernetes configurations as code. Use version control, review processes, and automated validation to maintain security integrity.

Conclusion

Connecting your EKS cluster to IAM roles is more than a technical configuration—it’s a strategic approach to cloud infrastructure management. By implementing flexible, secure access methods, you transform Kubernetes access from a complex challenge into a streamlined, intelligent system that adapts to your organization’s evolving needs. This approach not only simplifies authentication but also creates a robust framework for managing cloud resources with precision and confidence.

Key Takeaways

  • Flexibility is Power: Your IAM strategy should be as dynamic as your cloud infrastructure
  • Security is a Continuous Journey: Access management is an ongoing process of refinement
  • Visibility Enables Control: Transparent, manageable access mechanisms are your first line of defense

Additional Resources

Posted

in

,

by

Craig

Tags:

, , , , , ,