Kubernetes

Tokenless Authentication to Kubernetes using SAML.to

Introduction

The SAML.to or can be used for authentication to the Kubernetes Control Plane and be used with any tool that supports a kubeconfig file (such as kubectl, helm, k9s, etc.).

This document will detail how to use SAML.to to authenticate to the Kubernetes Control Plane for Tokenless authentication.

This page is focused for AWS EKS, however if you've manually provisioned your own cluster, you'll need to first set up the on your Kubernetes cluster.

Prerequisites

to your GitHub Organization or User Account
that will be used to access Kubernetes
- Grant yourself access in saml-to.yml for Testing purposes
- At a minimum, allow the role the eks:DescribeCluster permission
A Kubernetes Cluster and the ability to run kubectl commands on it

Create a Kubernetes Admin Role

Create a kubernetes-admin role (or whatever name you prefer) that has a .

At a minimum, the role needs permission to eks:DescribeCluster:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "eks:DescribeCluster",
      "Resource": "arn:aws:eks:*:*:cluster/*"
    }
  ]
}

Then, in saml-to.yml, grant access to GitHub Users to assume that role:

      - name: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
        ...
        users:
          github:
            - SOME_GITHUB_USERNAME
            - ANOTHER_GITHUB_USERNAME

Ensure the role is functional:

$(saml-to assume kubernetes-admin)
aws eks describe-cluster --name THE_CLUSTER_NAME [--region THE_CLUSTER_REGION]

Edit the Config Map

For brevity, these instructions will detail on how to map an IAM role to the system:masters group for full administrative control over Kubernetes.

In Kubernetes best practices, it is not recommended to grant access to system:masters .

Any group configuration is supported. Refer to the Kubernetes documentation for details on creating/using Cluster Roles and Cluster Role Bindings.

If the system was provisioned by AWS EKS, you should have an aws-auth ConfigMap in the kube-system namespace:

kubectl edit -n kube-system configmap/aws-auth

Add a section to mapRoles allowing the desired role access to the system:masters group:

    - groups:
        - system:masters
      rolearn: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
      username: kubernetes-admin

Connect to Kubernetes Using the Role

With The SAML.to CLI

Optional: Create or Update .kubeconfig

$(saml-to assume kubernetes-admin --headless)

aws eks update-kubeconfig --name THE_CLUSTER_NAME
kbectl set-context THE_CLUSTER_ARN

Run saml-to before kubectl commands as you normally would:

$(saml-to assume kubernetes-admin --headless)
kubectl get all -A

Kubernetes will do the rest of the work and map the active role in the Terminal Session to a group permission level as defined in mapRoles!

Running $(saml-to ...) before every Kubectl command is unnecessary.

The credentials will stay valid in your Terminal Session for how-ever long is defined in saml-to.yml the property value of https://aws.amazon.com/SAML/Attributes/SessionDuration, which defaults to 1 hour.

If the session expires, simply run the saml-to assume ... --headless command again!

Within GitHub Actions

A repository can also be granted access to the role. In your user's or organizations saml-to.yml, grant access for the Repository to gain access to the role:

      - name: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
        ...
        repos:
          github:
            - name: THE_REPO_NAME
            - name: SOME_OTHER_ORG/SOME_OTHER_REPO

      - name: Assume Role
        uses: saml-to/assume-aws-role-action@v1
        with:
          role: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
          region: THE_CLUSTER_REGION
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Login to Kubernetes
        run: aws eks update-kubeconfig --name THE_CLUSTER_NAME
        
      - name: Run a Kubernetes Command
        run: kubectl apply -f some-manifest.yaml

Questions/Comments/Issues?

PreviousTerraform NextAdding Users

Last updated 2 years ago

Introduction

The SAML.to or can be used for authentication to the Kubernetes Control Plane and be used with any tool that supports a kubeconfig file (such as kubectl, helm, k9s, etc.).

This document will detail how to use SAML.to to authenticate to the Kubernetes Control Plane for Tokenless authentication.

This page is focused for AWS EKS, however if you've manually provisioned your own cluster, you'll need to first set up the on your Kubernetes cluster.

Prerequisites

to your GitHub Organization or User Account
that will be used to access Kubernetes
- Grant yourself access in saml-to.yml for Testing purposes
- At a minimum, allow the role the eks:DescribeCluster permission
A Kubernetes Cluster and the ability to run kubectl commands on it

Create a Kubernetes Admin Role

Create a kubernetes-admin role (or whatever name you prefer) that has a .

At a minimum, the role needs permission to eks:DescribeCluster:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "eks:DescribeCluster",
      "Resource": "arn:aws:eks:*:*:cluster/*"
    }
  ]
}

Then, in saml-to.yml, grant access to GitHub Users to assume that role:

      - name: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
        ...
        users:
          github:
            - SOME_GITHUB_USERNAME
            - ANOTHER_GITHUB_USERNAME

Ensure the role is functional:

$(saml-to assume kubernetes-admin)
aws eks describe-cluster --name THE_CLUSTER_NAME [--region THE_CLUSTER_REGION]

Edit the Config Map

For brevity, these instructions will detail on how to map an IAM role to the system:masters group for full administrative control over Kubernetes.

In Kubernetes best practices, it is not recommended to grant access to system:masters .

Any group configuration is supported. Refer to the Kubernetes documentation for details on creating/using Cluster Roles and Cluster Role Bindings.

If the system was provisioned by AWS EKS, you should have an aws-auth ConfigMap in the kube-system namespace:

kubectl edit -n kube-system configmap/aws-auth

Add a section to mapRoles allowing the desired role access to the system:masters group:

    - groups:
        - system:masters
      rolearn: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
      username: kubernetes-admin

Connect to Kubernetes Using the Role

With The SAML.to CLI

Optional: Create or Update .kubeconfig

Using the with the --headless flag will update your Terminal Session with temporary AWS Session Tokens:

$(saml-to assume kubernetes-admin --headless)

aws eks update-kubeconfig --name THE_CLUSTER_NAME
kbectl set-context THE_CLUSTER_ARN

Run saml-to before kubectl commands as you normally would:

$(saml-to assume kubernetes-admin --headless)
kubectl get all -A

Kubernetes will do the rest of the work and map the active role in the Terminal Session to a group permission level as defined in mapRoles!

Running $(saml-to ...) before every Kubectl command is unnecessary.

If the session expires, simply run the saml-to assume ... --headless command again!

Within GitHub Actions

A repository can also be granted access to the role. In your user's or organizations saml-to.yml, grant access for the Repository to gain access to the role:

      - name: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
        ...
        repos:
          github:
            - name: THE_REPO_NAME
            - name: SOME_OTHER_ORG/SOME_OTHER_REPO

Then, in the GitHub action, use the to assume the role:

      - name: Assume Role
        uses: saml-to/assume-aws-role-action@v1
        with:
          role: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
          region: THE_CLUSTER_REGION
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Login to Kubernetes
        run: aws eks update-kubeconfig --name THE_CLUSTER_NAME
        
      - name: Run a Kubernetes Command
        run: kubectl apply -f some-manifest.yaml