How to Set Up Headlamp in minikube with Dex OIDC Authentication
In this tutorial, we'll walk through the process of configuring Headlamp within a Minikube cluster while utilizing Dex for OIDC (OpenID Connect) authentication. This tutorial is based on Dex version 2.38.0, Minikube version v1.31.2, and Headlamp version 0.22.0.
Configuring Dex
To enable OIDC authentication in your Minikube cluster, you'll need to configure Dex. Before proceeding, follow the getting started guide to set up your Dex instance. Follow these steps to configure Dex:
- Create a Dex configuration file. The following example demonstrates a basic configuration file for Dex, containing a static client, connector, and static password.
issuer: <YOUR-DEX-URL>
storage:
type: sqlite3
web:
http: 0.0.0.0:5556
staticClients:
- id: example-app
redirectURIs:
- "http://localhost:8000"
name: "Example App"
secret: ZXhhbXBsZS1hcHAtc2VjcmV0
connectors:
- type: mockCallback
id: mock
name: Example
# Let dex keep a list of passwords which can be used to login to dex.
enablePasswordDB: true
staticPasswords:
- email: "[email protected]"
# bcrypt hash of the string "password": $(echo password | htpasswd -BinC 10 admin | cut -d: -f2)
hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
username: "admin"
userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"
- Start Dex with the following command:
dex serve dex-config.yaml
Setting up Minikube with the Dex OIDC Configuration
To configure Minikube for Dex OIDC integration, follow these steps:
- Run the following command to start Minikube with the necessary configuration options:
minikube start -p=dex \
--extra-config=apiserver.authorization-mode=Node,RBAC \
--extra-config=apiserver.oidc-issuer-url=https://<YOUR-DEX-URL> \
--extra-config=apiserver.oidc-username-claim=email \
--extra-config=apiserver.oidc-client-id=<CLIENT-ID>
Note:
Replace <YOUR-DEX-URL>
with the actual URL of your Dex instance and <CLIENT-ID>
with the actual client ID.
Configuring a ClusterRole Binding for the OIDC User
Once your cluster is operational, you need to configure a cluster role and a cluster role binding for the Dex user. This step is essential for enabling the Kubernetes API server to identify the user. In this example, we'll be associating the user with the predefined cluster-admin
Role.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: admin-user-clusterrolebinding
subjects:
- kind: User
name: [email protected]
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: cluster-admin
apiGroup: rbac.authorization.k8s.io
Create the cluster role binding by running the following command:
kubectl apply -f clusterRoleBinding.yaml
Configuring kubectl for OIDC User Authentication
Once you've set up your cluster and created a ClusterRoleBinding, it's time to configure kubectl
to work with your OIDC user for authentication. Follow these steps:
- Install the
oidc-login
plugin with krew by executing the following command:
kubectl krew install oidc-login
- Set Up
oidc-login
, Configure oidc-login with the necessary parameters by running the following command:
kubectl oidc-login setup --oidc-issuer-url=https://<YOUR-DEX-URL> \ --oidc-client-id=<CLIENT-ID> \
--oidc-client-secret=<CLIENT-SECRET>
- Create OIDC User for the Cluster, later this user will be mapped to the dex cluster.
kubectl config set-credentials oidc-user \
--exec-api-version=client.authentication.k8s.io/v1beta1 \
--exec-command=kubectl \
--exec-arg=oidc-login \
--exec-arg=get-token \
--exec-arg=--oidc-issuer-url=<YOUR-DEX-URL> \
--exec-arg=--oidc-client-id=<CLIENT-ID> \
--exec-arg=--oidc-client-secret=<CLIENT-SECRET> \
--exec-arg=--oidc-extra-scope=email
- Link the User to the Cluster: To associate the user with the cluster, create a new context by running the following commands:
kubectl config set-context dex-oidc --namespace=default --cluster=dex --user=oidc-user
kubectl config use-context dex-oidc
- Test the Configuration: To verify that the configuration is working, list the namespaces in the cluster by executing the command:
kubectl get ns
Upon running this command, a new browser window will open, prompting you to log in. Once you've completed the login process, you can close the window. You should see the namespaces in your cluster.
Setting up Headlamp with Dex OIDC Authentication
To configure Headlamp, you can use the Headlamp Helm chart. Follow these steps to set it up with OIDC(OpenID Connect) authentication:
-
Before setting up Headlamp add
http://localhost:4466/oidc-callback
to theredirectURIs
in the Dex configuration. -
Create a
values.yaml
file and add the following OIDC configuration to it:
config:
oidc:
clientID: "<YOUR-CLIENT-ID>"
clientSecret: "<YOUR-CLIENT-SECRET>"
issuerURL: "<YOUR-DEX-URL>"
scopes: "email"
Replace <YOUR-CLIENT-ID>
,<YOUR-CLIENT-SECRET>
,<YOUR-DEX-URL>
with your specific OIDC configuration details.
- Save the
values.yaml
file and Install Headlamp using helm with the following commands:
helm repo add headlamp https://headlamp-k8s.github.io/headlamp/
helm install headlamp-oidc headlamp/headlamp -f values.yaml --namespace=headlamp --create-namespace
This will install Headlamp in the headlamp namespace with the OIDC configuration from the values.yaml file.
- After a successful installation, you can access Headlamp by port-forwarding to the pod:
kubectl port-forward svc/headlamp-oidc 4466:80 -n headlamp
- Open your web browser and go to http://localhost:4466. Click on "sign-in." After completing the login flow successfully, you'll gain access to your Kubernetes cluster using Headlamp.
Conclusion
In this tutorial, we've set up Headlamp within a Kubernetes cluster and integrated it with OIDC (OpenID Connect) authentication provided by Dex. By following the steps outlined in this guide, you've successfully configured Headlamp to enhance your Kubernetes cluster management.
This setup allows you to enjoy Headlamp's user-friendly interface and advanced features. You can also be assured of secure and streamlined authentication through Dex. With the power of OIDC, you can easily and safely access and manage your Kubernetes resources.