SSO for dashboard

Single Sign-On (SSO) with Keycloak for KubeOps Dashboard

This guide describes how to configure KubeOps Dashboard using Keycloak (OIDC) in a kubeops-managed Kubernetes environment.

Prerequisites

Before proceeding, ensure the following requirements are met:

• Keycloak is already installed and running
• kubeops is installed and operational

Step 1: Extract Keycloak CA certificate

• On your admin host, run the OpenSSL command (kept exactly as provided):

  openssl s_client -showcerts -connect dev04.kubeops.net:443 /dev/null | openssl x509 -outform PEM > keycloak-ca.crt

• Copy the CA certificate to each master

  scp :/etc/kubernetes/pki/

Step 2: Update kube-apiserver yaml

1. On every master, edit the yaml : /etc/kubernetes/manifests/kube-apiserver.yaml

   spec:
   
     containers:
   
     - command:
   
   
       - --oidc-issuer-url=https://dev04.kubeops.net/keycloak/realms/master
   
       - --oidc-client-id=headlamp
   
       - --oidc-username-claim=preferred_username
   
       - --oidc-groups-claim=groups
   
       - "--oidc-username-prefix=oidc:"
   
       - "--oidc-groups-prefix=oidc:"
   
       - --oidc-ca-file=/etc/kubernetes/pki/keycloak-ca.crt
   

Step 3: Create a Keycloak client for Headlamp

• Create a client for headlamp

  • Client ID: headlamp
  • Client type: OpenID Connect
  • Access type: Confidential
  • Client authentication: Enabled
  • Standard flow: Enabled
  • Direct access grants: Disabled

• Valid Redirect URIs

  Add the following redirect URI:

  https://headlamp/<your_DNS_name>/*
  

• Web Origins

  <your_DNS_name>
  

Step 4: Create a client scope for Headlamp

• Create a client scope

  • Assigned Client Scope : headlamp-dedicated

• For groups, use the Group Mapper in Keycloak:

  • Mapper Type: groups
  • Name: groups
  • Token Claim Name: groups
  • Add to ID token: ON
  • Add to access token: ON
  • Add to user info: ON
  • Add to token introspection: ON

Step 5: Create a user Group and user in Keycloak

Create a group named headlamp (if doesn’t exist already) and user under the group.

Step 6: Create ClusterRoleBinding for Headlamp group

1.Use following yaml to create ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRoleBinding

metadata:

  name: headlamp-admin-user

subjects:

- kind: Group

  name: "oidc:headlamp" # Der 'sub' oder 'preferred_username' from the Keycloak-Token

  apiGroup: rbac.authorization.k8s.io

roleRef:

  kind: ClusterRole

  name: cluster-admin

  apiGroup: rbac.authorization.k8s.io

The name “oidc:headlamp” needs to be the same as the group name.

2. Apply the ClusterRoleBinding file

    kubectl apply -f headlamp-clusterrolebinding.yaml

Step 7: Get client secret

After creating the client, copy the client secret.
This value will be used in the next step.

Step 8: Prepare Headlamp values (enterprise.yaml)

configure enterprise-yaml

packages:

- name: kubeops-dashboard

  enabled: true

  values:

    standard:

      namespace: monitoring

      service:

        nodePort: 30007

      hostname: "headlamp.dev04.kubeops.net"

      path: "/"

    advanced:

      config:

        extraArgs:

          - "--in-cluster"

          - "--plugins-dir=/headlamp/plugins"

          - "--oidc-client-id=headlamp"

          - "--oidc-idp-issuer-url=https://dev04.kubeops.net/keycloak/realms/master"

          - "--oidc-scopes=openid,profile,email"

          - "--insecure-ssl"

          - "--oidc-client-secret=<client-secret>"

Replace with the secret retrieved in Step 7.
-oidc-client-id must match the Keycloak client name (headlamp).

Step 9: Install Headlamp

Deploy Headlamp with the updated enterprise.yaml.