Authenticate to Kubernetes with OIDC on K3s
This recipe describes how to configure K3s for OIDC authentication against a Keycloak instance.
For details on why you'd want to do this, see the Kubernetes Authentication Guide.
Setup Keycloak for kube-apiserver
Start by logging into your Keycloak instance with a privileged account.
Navigate to Configure -> Clients, and Create a new client. I set the client ID to
kube-apiserver (you can't change it later):
That's it! You created your client!
Of course, it won't work yet, so there are a few tweaks we'll need..
Change Access Type to
confidential - this indicates to Keycloak that your client can be trusted to keep a secret safe, and thus that secret can be used in the OIDC credentials exchange.
Edit Redirect URIs, and add
What's that redirect URI for?
We'll use kubelogin to confirm OIDC login is working, which runs locally on port 18000 to provide a web-based OIDC login flow.
Save your settings, and observe that upon refresh, a new Credentials tab becomes available..
Navigate to Credentials, and make a note of the automatically generated client secret. You'll need this later for configuring your OIDC login.
Add mapper for groups
Finally, because we prefer to assign privileges to groups, rather than to individual users, navigate to Mappers, and create a new mapper as illustrated below:
This will send a
groups claim back to your OIDC client, with a list of your group memberships.
You can create whatever groups you prefer - later on, you'll configure clusterrolebindings to provide RBAC access to group members. I'd start with a group called
admin-kube-apiserver, which we'll simply map to the
Navigate to Manage -> Groups, create the necessary groups, and make yourself a member.
What have we achieved? We've configured Keycloak as an OIDC provider, and we've got the details necessary to configure our Kubernetes platform(s) to authenticate against it!
- keycloak configured as an OIDC provider for kube-apiserver
- OIDC parameters, including:
- OIDC Client id (
- OIDC Client secret (
<a randomly-generated secret>)
- OIDC Configuration URL (
- OIDC Client id (
Return to the Kubernetes Authentication Guide for instructions re configuring your particular Kubernetes platform!
Chef's notes 📓
Later on, as we add more applications which need kube-apiserver authentication, we'll add more redirect URIs. ↩
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.