Kubernetes
Tokenless Authentication to Kubernetes using SAML.to
Introduction
The SAML.to Command Line Interface or Assume AWS Role Action 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.
Prerequisites
SAML.to has been Installed to your GitHub Organization or User Account
A role (with a SAML.to Trust Relationship) that will be used to access Kubernetes
Grant yourself access in
saml-to.yml
for Testing purposesAt 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 Trust Relationship to SAML.to.
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
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
!
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 Assume AWS Role Action 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
Questions/Comments/Issues?
Last updated