Skip to content

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.

Requirements

Ingredients

Setup Keycloak for kube-apiserver

Start by logging into your Keycloak instance with a privileged account.

Create client

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!

Easy eh?

Of course, it won't work yet, so there are a few tweaks we'll need..

Access Type

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.

Redirect URIs

Edit Redirect URIs, and add http://localhost:18000 1

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.

Get credentials

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.

Create group

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 cluster-admin clusterrole.

Navigate to Manage -> Groups, create the necessary groups, and make yourself a member.

Summary

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!

Summary

Created:

  • keycloak configured as an OIDC provider for kube-apiserver
  • OIDC parameters, including:
    • OIDC Client id (kube-apiserver)
    • OIDC Client secret (<a randomly-generated secret>)
    • OIDC Configuration URL (https://<your-keycloak-host>/auth/realms/master/.well-known/openid-configuration)

What's next?

Return to the Kubernetes Authentication Guide for instructions re configuring your particular Kubernetes platform!

Chef's notes 📓

  1. 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.

Your comments? 💬