Skip to content

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.



Setup EKS for OIDC auth

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

.. some YAML.

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

kind: ClusterConfig

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

  - name: authentik
    type: oidc
    issuerUrl: # (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 \

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= --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": "",
  "sub": "363d4d0814dbad2d930308dc848342e328b76f925ebba0978a51ddad699022b",
  "aud": "kube-apiserver",
  "exp": 1701511022,
  "iat": 1698919022,
  "auth_time": 1698891834,
  "acr": "",
  "nonce": "qgKevTR1gU9Mh14HzOPPCTaP_Mgu9nvY7ZhJkCeFpGY",
  "at_hash": "TRZOLHHxFxl9HB7SHCIcMw",
  "email": "",
  "email_verified": true,
  "groups": [
    "authentik Admins",

Huzzah, authentication works! 🥳


Make sure you see a groups claim in the output above, and if you don't revisit your scope mapper and your claims in the provider under advanced protocol settings!

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: 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-command=kubectl \
 --exec-arg=oidc-login \
 --exec-arg=get-token \
 --exec-arg=--oidc-issuer-url= \
 --exec-arg=--oidc-client-id=kube-apiserver \
 --exec-arg=--oidc-client-secret=<your client secret> \
 --exec-arg=--oidc-extra-scope=profile \

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 "" 
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
  name: oidc-group-admin-kube-apiserver
  kind: ClusterRole
  name: cluster-admin # (1)!
- 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.


Run kubectl krew install whoami to install the whoami plugin, and then kubectl whoami to confirm you're logged in with your OIDC account

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


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.



  • EKS cluster with OIDC authentication against authentik
  • Ability to support:
    • Kubernetes Dashboard (coming soon)
    • Weave GitOps (coming soon)
  • We've also retained our static, IAM-based kubernetes-admin credentials in case OIDC auth fails at some point (keep them safe!)

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? 💬