mirror of
https://github.com/funkypenguin/geek-cookbook/
synced 2025-12-12 17:26:19 +00:00
Add OIDC with KeyCloak examples
Signed-off-by: David Young <davidy@funkypenguin.co.nz>
This commit is contained in:
David Young
@@ -34,6 +34,7 @@
|
||||
[k8s/mastodon]: /recipes/kubernetes/mastodon/
|
||||
[k8s/matrix]: /recipes/kubernetes/matrix/
|
||||
[k8s/authentik]: /recipes/kubernetes/authentik/
|
||||
[k8s/keycloak]: /recipes/kubernetes/keycloak/
|
||||
[k8s/matrix]: /recipes/kubernetes/matrix/
|
||||
[k8s/dashboard]: /recipes/kubernetes/dashboard/
|
||||
[k8s/oauth2proxy]: /recipes/kubernetes/oauth2-proxy/
|
||||
|
||||
BIN
docs/images/keycloak-kube-apiserver-1.png
Normal file
BIN
docs/images/keycloak-kube-apiserver-1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
BIN
docs/images/keycloak-kube-apiserver-2.png
Normal file
BIN
docs/images/keycloak-kube-apiserver-2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
BIN
docs/images/keycloak-kube-apiserver-3.png
Normal file
BIN
docs/images/keycloak-kube-apiserver-3.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 6.2 KiB |
BIN
docs/images/keycloak-kube-apiserver-4.png
Normal file
BIN
docs/images/keycloak-kube-apiserver-4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
BIN
docs/images/keycloak-kube-apiserver-5.png
Normal file
BIN
docs/images/keycloak-kube-apiserver-5.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
@@ -2,7 +2,7 @@
|
||||
title: Configure EKS for OIDC authentication with Authentik
|
||||
description: How to configure your EKS Kubernetes cluster for OIDC authentication with Authentik
|
||||
---
|
||||
# Authenticate to Kubernetes with OIDC on EKS
|
||||
# Authenticate to Kubernetes with authentik OIDC on EKS
|
||||
|
||||
This recipe describes how to configure an EKS cluster for OIDC authentication against an [authentik][k8s/authentik] instance.
|
||||
|
||||
|
||||
78
docs/kubernetes/oidc-authentication/eks-keycloak.md
Normal file
78
docs/kubernetes/oidc-authentication/eks-keycloak.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Configure EKS for OIDC authentication with Keycloak
|
||||
description: How to configure your EKS Kubernetes cluster for OIDC authentication with Keycloak
|
||||
---
|
||||
# Authenticate to Kubernetes with keycloak OIDC on EKS
|
||||
|
||||
This recipe describes how to configure an EKS cluster for OIDC authentication against a [Keycloak][k8s/keycloak] instance.
|
||||
|
||||
For details on **why** you'd want to do this, see the [Kubernetes Authentication Guide](/kubernetes/oidc-authentication/).
|
||||
|
||||
## Requirements
|
||||
|
||||
!!! summary "Ingredients"
|
||||
|
||||
* [x] A [Kubernetes cluster](/kubernetes/cluster/) deployed on Amazon EKS
|
||||
* [x] [Keycloak][k8s/keycloak] deployed per the recipe, secured with a valid SSL cert (*no self-signed schenanigans will work here!*)
|
||||
* [x] Keycloak additionally [configured as an OIDC provider for kube-apiserver](/kubernetes/oidc-authentication/keycloak/)
|
||||
* [x] `eksctl` tool configured and authorized for your IAM account
|
||||
|
||||
## Setup EKS for OIDC auth
|
||||
|
||||
In order to associate an OIDC provider with your EKS cluster[^1], you'll need (*guess what?*)..
|
||||
|
||||
.. some YAML.
|
||||
|
||||
Create an EKS magic YAML[^2] like this, and tweak it for your cluster name, region, and issuerUrl:
|
||||
|
||||
```yaml title="eks-cluster-setup.yaml"
|
||||
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:
|
||||
|
||||
|
||||
|
||||
{% include 'kubernetes-oidc-setup.md' %}
|
||||
|
||||
## 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.
|
||||
|
||||
!!! summary "Summary"
|
||||
Created:
|
||||
|
||||
* [X] EKS cluster with OIDC authentication against [authentik][k8s/authentik]
|
||||
* [X] Ability to support:
|
||||
* [X] Kubernetes Dashboard (*coming soon*)
|
||||
* [X] Weave GitOps (*coming soon*)
|
||||
* [X] 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!
|
||||
|
||||
[^1]: AWS docs are at https://docs.aws.amazon.com/eks/latest/userguide/authenticate-oidc-identity-provider.html
|
||||
[^2]: For details on available options, see https://docs.aws.amazon.com/cli/latest/reference/eks/associate-identity-provider-config.html
|
||||
|
||||
|
||||
{% include 'recipe-footer.md' %}
|
||||
@@ -2,7 +2,7 @@
|
||||
title: Configure K3s for OIDC authentication with Authentik
|
||||
description: How to configure your K3s Kubernetes cluster for OIDC authentication with Authentik
|
||||
---
|
||||
# Authenticate to Kubernetes with OIDC on K3s
|
||||
# Authenticate to Kubernetes with authentik OIDC on K3s
|
||||
|
||||
This recipe describes how to configure K3s for OIDC authentication against an [authentik][k8s/authentik] instance.
|
||||
|
||||
@@ -38,13 +38,11 @@ Here's the lunatic option:
|
||||
--kube-apiserver-arg=oidc-client-id=kube-apiserver
|
||||
--kube-apiserver-arg=oidc-username-claim=email
|
||||
--kube-apiserver-arg=oidc-groups-claim=groups
|
||||
--kube-apiserver-arg=oidc-username-prefix='oidc:'
|
||||
--kube-apiserver-arg=oidc-groups-prefix='oidc:'
|
||||
```
|
||||
|
||||
And here's the gentlemanly option:
|
||||
|
||||
Created `/etc/rancher/k3s/config.yaml`, and add:
|
||||
Create `/etc/rancher/k3s/config.yaml`, and add:
|
||||
|
||||
```yaml title="Gentlemanly YAML config option"
|
||||
kube-apiserver-arg:
|
||||
@@ -52,8 +50,6 @@ kube-apiserver-arg:
|
||||
- "oidc-client-id=kube-apiserver"
|
||||
- "oidc-username-claim=email"
|
||||
- "oidc-groups-claim=groups"
|
||||
- "oidc-username-prefix='oidc:'"
|
||||
- "oidc-groups-prefix='oidc:'"
|
||||
```
|
||||
|
||||
Now restart k3s (*`systemctl restart k3s` on Ubuntu*), and confirm it starts correctly by watching the logs (*`journalctl -u k3s -f` on Ubuntu*)
|
||||
@@ -76,7 +72,7 @@ kubectl oidc-login setup \
|
||||
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=profile,email
|
||||
~ ❯ kubectl oidc-login setup --oidc-issuer-url=https://authentik.example.com/application/o/kube-apiserver/ --oidc-client-id=kube-apiserver --oidc-client-secret=<your secret> --oidc-extra-scope=profile,email
|
||||
authentication in progress...
|
||||
|
||||
## 2. Verify authentication
|
||||
@@ -97,7 +93,7 @@ You got a token with the following claims:
|
||||
"email_verified": true,
|
||||
"groups": [
|
||||
"authentik Admins",
|
||||
"admin-kubernetes"
|
||||
"admin-kube-apiserver"
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -184,15 +180,15 @@ We've setup our K3s cluster to authenticate against authentik, running on that s
|
||||
!!! summary "Summary"
|
||||
Created:
|
||||
|
||||
* [X] EKS cluster with OIDC authentication against [authentik][k8s/authentik]
|
||||
* [X] K3s cluster with OIDC authentication against [authentik][k8s/authentik]
|
||||
* [X] Ability to support:
|
||||
* [X] Kubernetes Dashboard (*coming soon*)
|
||||
* [X] [Kubernetes Dashboard][k8s/dashboard]
|
||||
* [X] Weave GitOps (*coming soon*)
|
||||
* [X] We've also retained our static, IAM-based `kubernetes-admin` credentials in case OIDC auth fails at some point (*keep them safe!*)
|
||||
* [X] We've also retained our static, K3s-generated `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!
|
||||
Deploy Weave GitOps to visualize your Flux / GitOps state, and [Kubernetes Dashboard][k8s/dashboard] for UI management of your cluster!
|
||||
|
||||
[^1]: Later on, as we add more applications which need kube-apiserver authentication, we'll add more redirect URIs.
|
||||
|
||||
|
||||
207
docs/kubernetes/oidc-authentication/k3s-keycloak.md
Normal file
207
docs/kubernetes/oidc-authentication/k3s-keycloak.md
Normal file
@@ -0,0 +1,207 @@
|
||||
---
|
||||
title: Configure K3s for OIDC authentication with Keycloak
|
||||
description: How to configure your K3s Kubernetes cluster for OIDC authentication with Keycloak
|
||||
---
|
||||
# Authenticate to Kubernetes with Keycloak OIDC on K3s
|
||||
|
||||
This recipe describes how to configure K3s for OIDC authentication against a [Keycloak][k8s/keycloak] instance.
|
||||
|
||||
For details on **why** you'd want to do this, see the [Kubernetes Authentication Guide](/kubernetes/oidc-authentication/).
|
||||
|
||||
## Requirements
|
||||
|
||||
!!! summary "Ingredients"
|
||||
|
||||
* [x] A [Kubernetes cluster](/kubernetes/cluster/) deployed using [K3S](/kubernetes/cluster/k3s)
|
||||
* [x] [Keycloak][k8s/keycloak] deployed per the recipe
|
||||
* [x] Keycloak additionally [configured as an OIDC provider for kube-apiserver](/kubernetes/oidc-authentication/keycloak/)
|
||||
|
||||
## Setup K3s for OIDC auth
|
||||
|
||||
If you followed the k3s install guide, you'll have installed K3s with a command something like this:
|
||||
|
||||
```bash
|
||||
MYSECRET=iambatman
|
||||
curl -fL https://get.k3s.io | K3S_TOKEN=${MYSECRET} \
|
||||
sh -s - --disable traefik server
|
||||
```
|
||||
|
||||
To configure the apiserver to perform OIDC authentication, you need to add some extra kube-apiserver arguments. There are two ways to do this:
|
||||
|
||||
1. Append the arguments to your `curl | bash` command, like a lunatic
|
||||
2. Add the arguments to a config file which K3s will parse upon start, like a gentleman
|
||||
|
||||
Here's the lunatic option:
|
||||
|
||||
```bash title="Lunatic curl | bash option"
|
||||
--kube-apiserver-arg=oidc-issuer-url=https://keycloak.example.com/auth/realms/master/
|
||||
--kube-apiserver-arg=oidc-client-id=kube-apiserver
|
||||
--kube-apiserver-arg=oidc-username-claim=email
|
||||
--kube-apiserver-arg=oidc-groups-claim=groups
|
||||
```
|
||||
|
||||
And here's the gentlemanly option:
|
||||
|
||||
Create `/etc/rancher/k3s/config.yaml`, and add:
|
||||
|
||||
```yaml title="Gentlemanly YAML config option"
|
||||
kube-apiserver-arg:
|
||||
- "oidc-issuer-url=https://keycloak.example.com/auth/realms/master/"
|
||||
- "oidc-client-id=kube-apiserver"
|
||||
- "oidc-username-claim=email"
|
||||
- "oidc-groups-claim=groups"
|
||||
```
|
||||
|
||||
Now restart k3s (*`systemctl restart k3s` on Ubuntu*), and confirm it starts correctly by watching the logs (*`journalctl -u k3s -f` on Ubuntu*)
|
||||
|
||||
Assuming nothing explodes, you're good-to-go on attempting to actually connect...
|
||||
|
||||
### 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](https://github.com/int128/kubelogin), which is design suited to this purpose.
|
||||
|
||||
Use kubelogin to test your OIDC parameters, by running:
|
||||
|
||||
```bash
|
||||
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 Keycloak, and on the CLI you should get output something like this:
|
||||
|
||||
```
|
||||
~ ❯ kubectl oidc-login setup --oidc-issuer-url=https://keycloak.example.com/auth/realms/master/ --oidc-client-id=kube-apiserver --oidc-client-secret=<your secret>
|
||||
authentication in progress...
|
||||
|
||||
## 2. Verify authentication
|
||||
|
||||
You got a token with the following claims:
|
||||
|
||||
{
|
||||
"exp": 1700008379,
|
||||
"iat": 1700007479,
|
||||
"auth_time": 1700006251,
|
||||
"jti": "80760d79-3404-406c-bfd9-5c41783b0a5a",
|
||||
"iss": "https://keycloak.example/auth/realms/master",
|
||||
"aud": "kube-apiserver",
|
||||
"sub": "a612b1ae-63e1-4698-bcc8-9ba8b8b7fb84",
|
||||
"typ": "ID",
|
||||
"azp": "kube-apiserver",
|
||||
"nonce": "fwXjVCFM6xosn9yctYEducYBdy4KcnOqbaDxHPRWsTg",
|
||||
"session_state": "851804e4-e479-46ac-93b4-c89ac37aa7a3",
|
||||
"at_hash": "7lv4QY3h54maW6S5E--kgg",
|
||||
"acr": "0",
|
||||
"sid": "851804e4-e479-46ac-93b4-c89ac37aa7a3",
|
||||
"email_verified": false,
|
||||
"name": "David Young",
|
||||
"groups": [
|
||||
"admin-kiali",
|
||||
"admin-harbor",
|
||||
"admin-graylog",
|
||||
"admin-kubernetes",
|
||||
"concourse-main",
|
||||
"admin-keycloak",
|
||||
"admin-grafana"
|
||||
],
|
||||
"preferred_username": "davidy",
|
||||
"given_name": "David",
|
||||
"family_name": "Young",
|
||||
"email": "davidy@funkypenguin.co.nz"
|
||||
}
|
||||
```
|
||||
|
||||
Huzzah, authentication works! :partying_face:
|
||||
|
||||
!!! tip
|
||||
Make sure you see a groups claim in the output above, and if you don't, revisit your client's mapper settings as when you [configured as an OIDC provider for kube-apiserver](/kubernetes/oidc-authentication/keycloak/).
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
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://keycloak.example.com/auth/realms/master/ \
|
||||
--exec-arg=--oidc-client-id=kube-apiserver \
|
||||
--exec-arg=--oidc-client-secret=<your client secret>
|
||||
```
|
||||
|
||||
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! :scream:
|
||||
|
||||
```
|
||||
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:
|
||||
|
||||
```yaml title="/authentic/clusterrolebinding-oidc-group-admin-kube-apiserver.yaml"
|
||||
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`.
|
||||
|
||||
!!! tip "whoami?"
|
||||
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!
|
||||
|
||||
## Summary
|
||||
|
||||
What have we achieved?
|
||||
|
||||
We've setup our K3s 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 more access than they need, and we can deploy kube-apiserver-integrated tools like Kubernetes Dashboard or Weaveworks GitOps for nice secured UIs.
|
||||
|
||||
!!! summary "Summary"
|
||||
Created:
|
||||
|
||||
* [X] K3s cluster with OIDC authentication against [Keycloak][k8s/keycloak]
|
||||
* [X] Ability to support:
|
||||
* [X] [Kubernetes Dashboard][k8s/dashboard]
|
||||
* [X] Weave GitOps (*coming soon*)
|
||||
* [X] We've also retained our static, K3s-generated `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][k8s/dashboard] for UI management of your cluster!
|
||||
|
||||
[^1]: Later on, as we add more applications which need kube-apiserver authentication, we'll add more redirect URIs.
|
||||
|
||||
{% include 'recipe-footer.md' %}
|
||||
90
docs/kubernetes/oidc-authentication/keycloak.md
Normal file
90
docs/kubernetes/oidc-authentication/keycloak.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Configure K3s for OIDC authentication with Keycloak
|
||||
description: How to configure your Kubernetes cluster for OIDC authentication with Keycloak
|
||||
---
|
||||
# Authenticate to Kubernetes with OIDC on K3s
|
||||
|
||||
This recipe describes how to configure K3s for OIDC authentication against a [keycloak][k8s/keycloak] instance.
|
||||
|
||||
For details on **why** you'd want to do this, see the [Kubernetes Authentication Guide](/kubernetes/oidc-authentication/).
|
||||
|
||||
## Requirements
|
||||
|
||||
!!! summary "Ingredients"
|
||||
|
||||
* [x] A [Kubernetes cluster](/kubernetes/cluster/) deployed using [K3S](/kubernetes/cluster/k3s)
|
||||
* [x] [Keycloak][k8s/keycloak] deployed per the recipe
|
||||
|
||||
## Setup Keycloak for kube-apiserver
|
||||
|
||||
Start by logging into your [Keycloak][k8s/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]
|
||||
|
||||
|
||||
|
||||
!!! question "What's that redirect URI for?"
|
||||
We'll use [kubelogin](https://github.com/int128/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 "Summary"
|
||||
Created:
|
||||
|
||||
* [X] [keycloak][k8s/keycloak] configured as an OIDC provider for kube-apiserver
|
||||
* [X] OIDC parameters, including:
|
||||
* [X] OIDC Client id (`kube-apiserver`)
|
||||
* [X] OIDC Client secret (`<a randomly-generated secret>`)
|
||||
* [X] OIDC Configuration URL (`https://<your-keycloak-host>/auth/realms/master/.well-known/openid-configuration`)
|
||||
|
||||
What's next?
|
||||
|
||||
Return to the [Kubernetes Authentication Guide](/kubernetes/oidc-authentication/) for instructions re configuring your particular Kubernetes platform!
|
||||
|
||||
[^1]: Later on, as we add more applications which need kube-apiserver authentication, we'll add more redirect URIs.
|
||||
|
||||
{% include 'recipe-footer.md' %}
|
||||
131
docs/recipes/kubernetes/keycloak.md
Normal file
131
docs/recipes/kubernetes/keycloak.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: How to deploy Keycloak on Kubernetes
|
||||
description: Deploy Keycloak on Kubernetes to provide OIDC to your cluster and workloads
|
||||
values_yaml_url: https://github.com/bitnami/charts/blob/main/bitnami/keycloak/values.yaml
|
||||
helm_chart_version: 17.3.x
|
||||
helm_chart_name: keycloak
|
||||
helm_chart_repo_name: bitnami
|
||||
helm_chart_repo_url: oci://registry-1.docker.io/bitnamicharts/keycloak
|
||||
helmrelease_name: keycloak
|
||||
helmrelease_namespace: keycloak
|
||||
kustomization_name: keycloak
|
||||
slug: KeyCloak
|
||||
status: new
|
||||
upstream: https://www.keycloak.org
|
||||
links:
|
||||
- name: GitHub Repo
|
||||
uri: https://github.com/keycloak/keycloak
|
||||
---
|
||||
|
||||
# KeyCloak installation on Kubernetes
|
||||
|
||||
[Keycloak](https://www.keycloak.org/) is "_an open source identity and access management solution_". Using a local database, or a variety of backends (_think [OpenLDAP](/recipes/openldap/)_), you can provide Single Sign-On (SSO) using OpenID, OAuth 2.0, and SAML.
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
Keycloak's OpenID provider can also be used to provide [OIDC-based authentication to your Kubernetes cluster](/kubernetes/oidc-authentication/), or in combination with [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/), to protect [vulnerable services](/recipes/autopirate/nzbget/) with an extra layer of authentication.
|
||||
|
||||
## {{ page.meta.slug }} requirements
|
||||
|
||||
!!! summary "Ingredients"
|
||||
|
||||
Already deployed:
|
||||
|
||||
* [x] A [Kubernetes cluster](/kubernetes/cluster/)
|
||||
* [x] [Flux deployment process](/kubernetes/deployment/flux/) bootstrapped
|
||||
* [x] An [Ingress controller](/kubernetes/ingress/) to route incoming traffic to services
|
||||
* [x] [Persistent storage](/kubernetes/persistence/) to store persistent stuff
|
||||
|
||||
Optional:
|
||||
|
||||
* [ ] [External DNS](/kubernetes/external-dns/) to create an DNS entry the "flux" way
|
||||
|
||||
{% include 'kubernetes-flux-namespace.md' %}
|
||||
{% include 'kubernetes-flux-helmrepository.md' %}
|
||||
{% include 'kubernetes-flux-kustomization.md' %}
|
||||
{% include 'kubernetes-flux-dnsendpoint.md' %}
|
||||
{% include 'kubernetes-flux-helmrelease.md' %}
|
||||
|
||||
## Configure Keycloak Helm Chart
|
||||
|
||||
The following sections detail suggested changes to the values pasted into `/{{ page.meta.helmrelease_namespace }}/helmrelease-{{ page.meta.helmrelease_name }}.yaml` from the {{ page.meta.slug }} helm chart's [values.yaml]({{ page.meta.values_yaml_url }}). The values are already indented correctly to be copied, pasted into the HelmRelease, and adjusted as necessary.
|
||||
|
||||
### Ingress
|
||||
|
||||
Setup your ingress for the KeyCloak UI, enabling at least `ingress.enabled` as below, and additional TLS options as necessary[^1]:
|
||||
|
||||
```yaml hl_lines="4" title="Configure your ingress"
|
||||
ingress:
|
||||
## @param ingress.enabled Enable ingress record generation for Keycloak
|
||||
##
|
||||
enabled: false
|
||||
```
|
||||
|
||||
Either leave blank to accept the default ingressClassName, or set to whichever [ingress controller](/kubernetes/ingress/) you want to use.
|
||||
|
||||
## Install {{ page.meta.slug }}!
|
||||
|
||||
Commit the changes to your flux repository, and either wait for the reconciliation interval, or force a reconcilliation using `flux reconcile source git flux-system`. You should see the kustomization appear...
|
||||
|
||||
```bash
|
||||
~ ❯ flux get kustomizations {{ page.meta.kustomization_name }}
|
||||
NAME READY MESSAGE REVISION SUSPENDED
|
||||
{{ page.meta.kustomization_name }} True Applied revision: main/70da637 main/70da637 False
|
||||
~ ❯
|
||||
```
|
||||
|
||||
The helmrelease should be reconciled...
|
||||
|
||||
```bash
|
||||
~ ❯ flux get helmreleases -n {{ page.meta.helmrelease_namespace }} {{ page.meta.helmrelease_name }}
|
||||
NAME READY MESSAGE REVISION SUSPENDED
|
||||
{{ page.meta.helmrelease_name }} True Release reconciliation succeeded v{{ page.meta.helm_chart_version }} False
|
||||
~ ❯
|
||||
```
|
||||
|
||||
And you should have happy pods in the {{ page.meta.helmrelease_namespace }} namespace:
|
||||
|
||||
```bash
|
||||
~ ❯ k get pods -n keycloak
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
keycloak-0 1/1 Running 1 (3d17h ago) 26d
|
||||
keycloak-postgresql-0 1/1 Running 1 (3d17h ago) 26d
|
||||
~ ❯
|
||||
```
|
||||
|
||||
Browse to the URL you configured in your ingress above, and confirm that the KeyCloak UI is displayed. Login with the admin user you defined above, and confirm a successful login.
|
||||
|
||||
### Create Keycloak user
|
||||
|
||||
!!! question "Why are we adding a user when I have an admin user already?"
|
||||
Do you keep a spare set of house keys somewhere _other_ than your house? Do you login as `root` onto all your systems? Think of this as the same prinicple - lock the literal `admin` account away somewhere as a "password of last resort", and create a new user for your day-to-day interaction with Keycloak.
|
||||
|
||||
Within the "Master" realm (_no need for more realms unless you want to_), navigate to **Manage** -> **Users**, and then click **Add User** at the top right:
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
Populate your new user's username (it's the only mandatory field)
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
#### Set Keycloak user credentials
|
||||
|
||||
Once your user is created, to set their password, click on the "**Credentials**" tab, and procede to reset it. Set the password to non-temporary, unless you like extra work!
|
||||
|
||||
{ loading=lazy }
|
||||
## Summary
|
||||
|
||||
What have we achieved? We've got Keycloak running and accessible, we've created our normal-use user, and we're ready to flex :muscle: the power of Keycloak to deploy an [OIDC provider for Kubernetes](/kubernetes/oidc-authentication/), or to provide OIDC to [Traefik Forward Auth][tfa] to protect vulnerable UIs!
|
||||
|
||||
!!! summary "Summary"
|
||||
Created:
|
||||
|
||||
* [X] Keycloak running and ready for authentication :lock: !
|
||||
|
||||
Next:
|
||||
|
||||
* [ ] Configure [Kubernetes OIDC authentication](/kubernetes/oidc-authentication/), unlocking production readiness as well as the [Kubernetes Dashboard][k8s/dashboard] and Weave GitOps UIs (*coming soon*)
|
||||
|
||||
{% include 'recipe-footer.md' %}
|
||||
|
||||
[^1]: There's a trick to using a single cert across multiple Ingresses or IngressRoutes (coming soon)
|
||||
Reference in New Issue
Block a user