Using OpenID Connect with Cozystack on Cozystack

Enable OIDC Server

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

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"

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

Creating users and add roles for them

Mon, 01 Jan 0001 00:00:00 +0000

Creating users and add roles for them

Overview

When a tenant is created in Cozy (starting with version 1.6.0), roles, RoleBindings and keycloak groups will automatically be created in the Kubernetes cluster.

To create a user, refer to the following documentation: Keycloak Admin Console Documentation

Assigning a Role to a User for a Tenant

Access Keycloak: To retrieve login credentials, check the secret by running the following command:

kubectl get secret keycloak-credentials -n cozy-keycloak -o yaml

Keycloak Address: The Keycloak address will match the value specified in the cozystack ConfigMap. For example, if your ConfigMap looks like this:

 apiVersion: v1
 kind: ConfigMap
 metadata:
 name: cozystack
 namespace: cozy-system
 data:
 root-host: infra.example.org
 api-server-adress: 55.21.33.22
 bundle-name: "paas-full"
 ipv4-pod-cidr: "10.244.0.0/16"
 ipv4-pod-gateway: "10.244.0.1"
 ipv4-svc-cidr: "10.96.0.0/16"
 ipv4-join-cidr: "100.64.0.0/16"

Then Keycloak will be available at: keycloak.infra.example.org

If you are planning to integrate with external services either as clients or as IdPs, your Keycloak address needs to be publicly accessible and reachable by these services.

Configure Roles for Each Tenant in Cozy:

Cluster wide

cozystack-cluster-admin

Self-Signed Certificates

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to configure Kubernetes API server for OIDC authentication with Keycloak when using self-signed certificates. By default, Cozystack issues certificates via LetsEncrypt, but some environments (e.g., air-gapped or private enterprise networks) may use a custom CA instead.

Prerequisites

Cozystack cluster with OIDC enabled (see Enable OIDC Server)
Talos Linux control plane nodes
talosctl configured for your cluster
kubelogin installed

Step 1: Retrieve the Keycloak Certificate

Get the certificate from the ingress controller: