Aller au contenu

Keycloak

Authentification unique, gestion des identités et contrôle d'accès basé sur les rôles.
URL https://identity.akko.local
Console d'administration https://identity.akko.local/admin/
Service Docker keycloak

Aperçu

Keycloak est le fournisseur d'identité de l'ensemble de la plateforme AKKO. Chaque service disposant d'une interface web s'authentifie via Keycloak en utilisant OAuth2 / OpenID Connect, offrant une expérience de connexion unifiée à travers tous les outils.

Fonctionnalités clés :

  • Single Sign-On (SSO) -- connectez-vous une fois, accédez à tous les services
  • Contrôle d'accès basé sur les rôles (RBAC) -- cinq rôles plateforme contrôlent ce que les utilisateurs peuvent voir et faire
  • Export du realm -- la configuration complète est versionnée dans keycloak/realm-akko.json
  • Protection contre la force brute -- activée par défaut (verrouillage après 5 tentatives échouées)

Realm : akko

Toute la configuration AKKO réside dans un seul realm Keycloak nommé akko. Le realm est importé automatiquement au premier démarrage depuis keycloak/realm-akko.json.

Paramètres clés du realm :

Paramètre Valeur
Nom du realm akko
Nom d'affichage AKKO
Thème de connexion akko (personnalisé)
Algorithme de signature RS256
Durée de vie du jeton d'accès 300 secondes (5 min)
Délai d'inactivité de session SSO 1800 secondes (30 min)
Durée de vie maximale de session SSO 36000 secondes (10 heures)
Inscription Désactivée
Protection force brute Activée (5 échecs, verrouillage de 5 min)

Clients OAuth2

Le realm inclut 13 clients OAuth2 (10 services AKKO + 3 clients Keycloak internes exposés par défaut) :

Client Type Service
jupyterhub Confidentiel Environnement de notebooks JupyterHub
superset Confidentiel Apache Superset BI
airflow Confidentiel Orchestration Apache Airflow
grafana Confidentiel Tableaux de bord Dashboards
trino Confidentiel Moteur SQL Trino
polaris Confidentiel Catalogue Apache Polaris
openmetadata Confidentiel Gouvernance OpenMetadata
oauth2-proxy Confidentiel OAuth2 Proxy (protège les services sans OAuth natif)
minio Confidentiel Console stockage objet
svc-cockpit-admin Confidentiel Compte de service Cockpit (API Admin Keycloak)
account Public Gestion de compte Keycloak (intégré)
admin-cli Public CLI d'administration Keycloak (intégré)
realm-management Confidentiel Gestion du realm Keycloak (intégré)

Clients Keycloak supplémentaires

Keycloak embarque aussi account-console, broker et security-admin-console dans chaque realm pour sa propre UI d'admin. Ils ne sont pas comptés dans les « 13 clients » car ils sont internes à Keycloak et non consommés par les services AKKO.

Clients confidentiels vs publics

Les clients confidentiels utilisent un secret client pour le flux par code d'autorisation côté serveur. Les clients publics utilisent PKCE pour les flux navigateur. OpenMetadata nécessite spécifiquement un client confidentiel pour éviter les boucles de connexion avec les certificats auto-signés dans Safari.

Rôles RBAC

Cinq rôles à l'échelle de la plateforme contrôlent l'accès à travers tous les services :

Rôle Description Accès typique
akko-admin Administrateur de la plateforme Accès complet à tous les services, consoles d'administration, opérations DDL
akko-engineer Ingénieur de données Spark, Airflow, Trino DDL, écriture notebook, gestion de pipelines
akko-analyst Analyste de données Notebooks, Superset, Trino en lecture seule, navigation dans le catalogue
akko-user Utilisateur standard / conformité Trino en lecture seule avec masquage PII, audit, navigation dans le catalogue
akko-viewer Visualiseur de tableaux de bord Tableaux de bord Superset (lecture seule), tableaux de bord Dashboards

Rôle par défaut

Les nouveaux utilisateurs se voient automatiquement attribuer le rôle akko-analyst via le rôle composite default-roles-akko.

Pour la matrice d'accès complète (par service, par catalogue, masquage de colonnes, filtrage par lignes), voir le Guide d'administration RBAC.

Utilisateurs par défaut

Cinq utilisateurs de test sont pré-configurés dans le realm :

Nom d'utilisateur Rôle Mot de passe Description
alice akko-admin alice123 (dev) Administratrice de la plateforme
bob akko-engineer bob123 (dev) Ingénieur de données
carol akko-analyst carol123 (dev) Analyste de données
eve akko-user eve123 (dev) Utilisatrice standard
dave akko-viewer dave123 (dev) Visualiseur de tableaux de bord

emailVerified doit être true

Tous les utilisateurs doivent avoir emailVerified=true dans Keycloak. Le service oauth2-proxy rejette les utilisateurs sans email vérifié, provoquant des échecs de connexion pour JupyterHub et les autres services protégés par proxy.

Console d'administration

La console d'administration Keycloak est accessible à :

https://identity.akko.local/admin/

Les identifiants d'administration sont définis dans les valeurs Helm (global.auth.keycloakAdminPassword) et stockés dans le Secret Kubernetes akko-keycloak.

Depuis la console d'administration, vous pouvez :

  • Gérer les utilisateurs (créer, désactiver, réinitialiser les mots de passe)
  • Attribuer des rôles et des groupes
  • Configurer les clients OAuth2
  • Consulter les sessions actives
  • Surveiller les événements de connexion et les erreurs

Ajouter un nouvel utilisateur

  1. Ouvrez la console d'administration à https://identity.akko.local/admin/
  2. Sélectionnez le realm akko (menu déroulant en haut à gauche)
  3. Naviguez vers Users > Add user
  4. Remplissez :
    • Nom d'utilisateur (obligatoire)
    • Email (obligatoire)
    • Prénom, Nom
    • Basculez Email verified sur ON
  5. Cliquez sur Create
  6. Allez dans l'onglet Credentials et définissez un mot de passe
  7. Allez dans l'onglet Role mapping :
    • Cliquez sur Assign role
    • Filtrez par rôles du realm
    • Sélectionnez le rôle approprié (akko-admin, akko-engineer, akko-analyst ou akko-viewer)

Configuration persistante

Les modifications utilisateur effectuées dans la console d'administration sont stockées dans la base de données PostgreSQL de Keycloak et survivent aux redémarrages. Elles ne sont pas réécrites dans realm-akko.json. Pour exporter l'état actuel du realm :

kubectl exec -n akko deploy/akko-keycloak -- /opt/keycloak/bin/kc.sh export \
    --dir /opt/keycloak/data/export \
    --realm akko

Ajouter un nouveau client de service

Lors de l'ajout d'un nouveau service à AKKO nécessitant l'authentification Keycloak :

  1. Ouvrez la console d'administration et naviguez vers Clients > Create client
  2. Définissez le Client ID (par ex. my-service)
  3. Choisissez Client authentication = ON pour les clients confidentiels
  4. Configurez les Valid redirect URIs : https://my-service.akko.local/*
  5. Configurez les Web origins : https://my-service.akko.local
  6. Sauvegardez et copiez le secret client depuis l'onglet Credentials
  7. Ajoutez la configuration du client dans keycloak/realm-akko.json pour le contrôle de version

Problèmes connus

KC_HOSTNAME, pas KC_HOSTNAME_URL

Keycloak 26.x utilise la configuration hostname v2. La variable d'environnement est KC_HOSTNAME (pas KC_HOSTNAME_URL, qui est v1 et silencieusement ignorée). Utilisez KC_HOSTNAME_BACKCHANNEL_DYNAMIC: false pour un émetteur (issuer) cohérent entre l'accès interne et externe.

L'import du realm se fait uniquement au premier démarrage

Le fichier realm-akko.json est importé lorsque la base de données Keycloak est vide (premier démarrage). Les modifications ultérieures du fichier JSON ne seront pas appliquées automatiquement. Réimportez manuellement ou effectuez les modifications via la console d'administration.

Persistance des mots de passe dans PostgreSQL

Keycloak stocke ses données dans PostgreSQL. Si vous régénérez le fichier .env avec de nouveaux mots de passe, l'ancien mot de passe administrateur Keycloak persiste dans la base de données. Vous devez soit :

  • Réinitialiser via ALTER USER dans PostgreSQL
  • Soit supprimer le volume Keycloak : docker volume rm akko_keycloak-data