Enable OIDC Server

Prerequisites

1. OIDC Configuration Your API server must be configured to use OIDC. If you are using Talos Linux, your machine configuration should include the following parameters:

   cluster:
     apiServer:
       extraArgs:
         oidc-issuer-url: "https://keycloak.example.org/realms/cozy"
         oidc-client-id: "kubernetes"
         oidc-username-claim: "preferred_username"
         oidc-groups-claim: "groups"
   

   For Talm Add to your values.yaml in talm repo:

   oidcIssuerUrl: "https://keycloak.<YOUR_ROOT_DOMAIN>/realms/cozy"
   

2. Domain Reachability Ensure that the domain keycloak.example.org is accessible from the cluster and resolves to your root ingress controller.

3. Storage Configuration Storage must be properly configured.

Configuration

If all prerequisites are met, you can proceed with the configuration steps.

Step 1: Enable OIDC in Cozystack

Edit your Cozystack ConfigMap to enable OIDC, this also will expose keycloak service automatically:

kubectl patch -n cozy-system configmap cozystack --type=merge -p '{
  "data": {
    "oidc-enabled": "true"
  }
}'

If you need to add extra redirect URLs for the dashboard client (for example, when accessing the dashboard via port-forwarding), edit your Cozystack ConfigMap. Multiple redirect URLs should be separated by commas.

kubectl patch -n cozy-system configmap cozystack --type=merge -p '{"data":{"extra-keycloak-redirect-uri-for-dashboard": "http://127.0.0.1:8080/oauth2/callback/*,http://localhost:8080/oauth2/callback/*"}}'

Within one minute, CozyStack will reconcile the ConfigMap and create three new HelmRelease resources:

# kubectl get hr -n cozy-keycloak
cozy-keycloak                    keycloak                    26s    Unknown   Running 'install' action with a timeout of 5m0s
cozy-keycloak                    keycloak-configure          26s    False     dependency 'cozy-keycloak/keycloak-operator' is not ready
cozy-keycloak                    keycloak-operator           26s    False     dependency 'cozy-keycloak/keycloak' is not ready

Step 2: Wait for Installation Completion

Wait until all resources are successfully installed and reach the Ready state:

NAME                 AGE     READY   STATUS
keycloak             2m19s   True    Release reconciliation succeeded
keycloak-configure   2m19s   True    Release reconciliation succeeded
keycloak-operator    2m19s   True    Release reconciliation succeeded

Reconcile tenants:

kubectl annotate -n tenant-root hr/tenant-root reconcile.fluxcd.io/forceAt=$(date +"%Y-%m-%dT%H:%M:%SZ") --overwrite

Step 3: Access Keycloak

You can now access Keycloak at https://keycloak.example.org (replace example.org with your infrastructure domain).

To get the Keycloak credentials for default user admin, run the following command:

kubectl get secret -o yaml -n cozy-keycloak keycloak-credentials -o go-template='{{ printf "%s\n" (index .data "password" | base64decode) }}'

1. Switch realm to cozy.

2. Create a user in the realm cozy.

   Follow the Keycloak documentation to create a user in the realm cozy.

3. After a user is created, go to the user details in Keycloak admin console and turn on the “Verified email” toggle. This is needed for OIDC authentication to work properly.

4. Add the user to the cozystack-cluster-admin group.

5. Now you should be able to login to the dashboard using your OIDC credentials.

   If the dashboard is still requesting a token instead of login/password, manually reconcile it:

   kubectl annotate helmrepositories.source.toolkit.fluxcd.io -n cozy-dashboard dashboard reconcile.fluxcd.io/requestedAt=$(date +"%Y-%m-%dT%H:%M:%SZ") --overwrite
   

Step 4: Retrieve Kubeconfig

To access the cluster through the Dashboard, download your kubeconfig by selecting the deployed tenant and copying the secret from the resource map.

This kubeconfig will be automatically configured to use OIDC authentication and the namespace dedicated to the tenant.

Setup kubelogin which is necessary to use an OIDC-enabled kubeconfig.

# Homebrew (macOS and Linux)
brew install int128/kubelogin/kubelogin

# Krew (macOS, Linux, Windows and ARM)
kubectl krew install oidc-login

# Chocolatey (Windows)
choco install kubelogin