Authenticate to Kubernetes with keycloak OIDC on EKS

This recipe describes how to configure an EKS cluster for OIDC authentication against a Keycloak instance.

For details on why you'd want to do this, see the Kubernetes Authentication Guide.

Requirements

Setup EKS for OIDC auth

In order to associate an OIDC provider with your EKS cluster¹, you'll need (guess what?)..

.. some YAML.

Create an EKS magic YAML² like this, and tweak it for your cluster name, region, and issuerUrl:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: funkypenguin-authentik-test
  region: ap-southeast-2

identityProviders:
  - name: authentik
    type: oidc
    issuerUrl: https://keycloak.funkypenguin.de/auth/realms/master/ # (1)! 
    clientId: kube-apiserver
    usernameClaim: email
    groupsClaim: groups

1. Make sure this ends in a /, and doesn't include .well-known/openid-configuration

Apply the EKS magic by running eksctl associate identityprovider -f eks-cluster-setup.yaml

That's it! It may take a few minutes (you can verify it's ready on your EKS console), but once complete, the authentik provider should be visible in your cluster console, under the "Authentication" tab, as illustrated below:

Install kubelogin

For CLI-based access to your cluster, you'll need a "helper" to perform the OIDC magic on behalf of kubectl. Install int128/kubelogin, which is design suited to this purpose.

Use kubelogin to test your OIDC parameters, by running:

kubectl oidc-login setup \
  --oidc-issuer-url=ISSUER_URL \
  --oidc-client-id=YOUR_CLIENT_ID \
  --oidc-client-secret=YOUR_CLIENT_SECRET

All going well, your browser will open a new window, logging you into authentik, and on the CLI you should get output something like this:

~ ❯ kubectl oidc-login setup --oidc-issuer-url=https://authentik.example.com/application/o/kube-apiserver/ --oidc-client-id=kube-apiserver --oidc-client-secret=cVj4YqmB4VPcq6e7 --oidc-extra-scope=groups,email
authentication in progress...

## 2. Verify authentication

You got a token with the following claims:

{
  "iss": "https://authentik.example.com/application/o/kube-apiserver/",
  "sub": "363d4d0814dbad2d930308dc848342e328b76f925ebba0978a51ddad699022b",
  "aud": "kube-apiserver",
  "exp": 1701511022,
  "iat": 1698919022,
  "auth_time": 1698891834,
  "acr": "goauthentik.io/providers/oauth2/default",
  "nonce": "qgKevTR1gU9Mh14HzOPPCTaP_Mgu9nvY7ZhJkCeFpGY",
  "at_hash": "TRZOLHHxFxl9HB7SHCIcMw",
  "email": "davidy@example.com",
  "email_verified": true,
  "groups": [
    "authentik Admins",
    "admin-kubernetes"
  ]
}

Huzzah, authentication works!

Assemble your kubeconfig

Your kubectl access to k3s uses a kubeconfig file at /etc/rancher/k3s/k3s.yaml. Treat this file as a root password - it's includes a long-lived token which gives you clusteradmin ("god mode" on your cluster.)

Copy the k3s.yaml file to your local desktop (the one with a web browser), into $HOME/.kube/config, and modify it, changing server: https://127.0.0.1:6443 to match the URL of (one of) your control-plane node(s).

Test using kubectl cluster-info locally, ensuring that you have access.

Amend the kubeconfig file for your OIDC user, by running a variation of:

kubectl config set-credentials oidc \
 --exec-api-version=client.authentication.k8s.io/v1beta1 \
 --exec-command=kubectl \
 --exec-arg=oidc-login \
 --exec-arg=get-token \
 --exec-arg=--oidc-issuer-url=https://authentik.example.com/application/o/kube-apiserver/ \
 --exec-arg=--oidc-client-id=kube-apiserver \
 --exec-arg=--oidc-client-secret=<your client secret> \
 --exec-arg=--oidc-extra-scope=profile \
 --exec-arg=--oidc-extra-scope=email

Test your OIDC powerz by running kubectl --user=oidc cluster-info.

Now gasp in dismay as you discover that your request was denied for lack of access!

Error from server (Forbidden): services is forbidden: User "oidc:davidy@funkypenguin.co.nz" 
cannot list resource "services" in API group "" in the namespace "kube-system"

Create clusterrolebinding

That's what you wanted, right? Security? Locking out unauthorized users? Ha.

Now that we've confirmed that kube-apiserver knows your identity (authn), create a clusterrolebinding to tell it what your identity is authorized to do (authz), based on your group membership.

The following is a simple clusterrolebinding which will grant all members of the admin-kube-apiserver full access (cluster-admin), to get you started:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: oidc-group-admin-kube-apiserver
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin # (1)!
subjects:
- kind: Group
  name: oidc:admin-kube-apiserver # (2)!

1. The role to bind
2. The subject (group, in this case) of the binding

Apply your clusterrolebinding using the usual GitOps magic (I put mine in /authentic/clusterrolebinding-oidc-group-admin-kube-apiserver.yaml).

Run kubectl --user=oidc cluster-info again, and confirm you are now authorized to see the cluster details.

If this works, set your user context permanently, using kubectl config set-context --current --user=oidc.

You now have OIDC-secured CLI access to your cluster!

Summary

What have we achieved?

We've setup our EKS cluster to authenticate against Keycloak, running on that same cluster! We can now create multiple users (with multiple levels of access) without having to provide them with tricky IAM accounts, and deploy kube-apiserver-integrated tools like Kubernetes Dashboard or Weaveworks GitOps for nice secured UIs.

What's next?

Deploy Weave GitOps to visualize your Flux / GitOps state, and Kubernetes Dashboard for UI management of your cluster!

Chef's notes 📓

Tip your waiter (sponsor) 👏

Did you receive excellent service? Want to compliment the chef? (..and support development of current and future recipes!) Sponsor me on Github / Ko-Fi / Patreon, or see the contribute page for more (free or paid) ways to say thank you! 👏

Employ your chef (engage) 🤝

Is this too much of a geeky PITA? Do you just want results, stat? I do this for a living - I'm a full-time Kubernetes contractor, providing consulting and engineering expertise to businesses needing short-term, short-notice support in the cloud-native space, including AWS/Azure/GKE, Kubernetes, CI/CD and automation.

Learn more about working with me here.

Flirt with waiter (subscribe) 💌

Want to know now when this recipe gets updated, or when future recipes are added? Subscribe to the RSS feed, or leave your email address below, and we'll keep you updated.

Your comments? 💬