Aller au contenu

Intégration d'un Fournisseur d'Identité Externe

Ce guide explique comment connecter AKKO au fournisseur d'identité (IdP) existant de votre organisation. AKKO utilise Keycloak comme courtier d'identité, qui prend en charge pratiquement tous les IdP basés sur OIDC ou LDAP.

Vue d'ensemble

Par défaut, AKKO est livré en mode demo avec un annuaire directory service intégré et des utilisateurs préconfigurés. En production, vous souhaiterez connecter votre système d'identité d'entreprise à la place. AKKO supporte trois schémas d'intégration :

Schéma Type d'IdP Fonctionnalité Keycloak Cas d'usage
Courtage d'identité Azure AD, Okta, Google Identity Providers (OIDC) SSO cloud natif
Fédération d'utilisateurs Active Directory, OpenLDAP User Federation (LDAP) Annuaire sur site
Courtage SAML N'importe quel IdP SAML 2.0 Identity Providers (SAML) SSO d'entreprise historique

Tous les schémas aboutissent à des utilisateurs visibles dans Keycloak avec les rôles AKKO, permettant un SSO transparent à travers les 33+ services de la plateforme.

Passer en mode entreprise

Définissez le mode de déploiement dans votre fichier de valeurs :

# values-enterprise.yaml (ou values-production.yaml)
global:
  auth:
    mode: "enterprise"

    # Administrateur initial créé avant que la fédération soit active
    initialAdmin:
      enabled: true
      username: "admin-akko"
      email: "admin@corp.example.com"

# Désactiver le service d'annuaire intégré — votre IdP d'entreprise le remplace
akko-lldap:
  enabled: false

Voir helm/examples/values-enterprise.yaml pour un exemple complet fonctionnel.

1. Azure AD / Entra ID (courtage OIDC)

Étape 1 : Créer une inscription d'application dans Azure

  1. Allez dans Portail Azure > Microsoft Entra ID > Inscriptions d'applications > Nouvelle inscription
  2. Configurez :
  3. Nom : AKKO Platform
  4. Types de comptes pris en charge : Locataire unique (votre organisation seulement)
  5. URI de redirection : https://keycloak.<votre-domaine>/realms/akko/broker/azure-ad/endpoint
  6. Après la création, notez l'ID d'application (client) et l'ID de répertoire (locataire)
  7. Allez dans Certificats et secrets > Nouveau secret client et notez la Valeur
  8. Allez dans Permissions d'API > Ajouter une permission > Microsoft Graph :
  9. openid, profile, email, User.Read
  10. Optionnel : GroupMember.Read.All (pour la synchronisation des groupes)
  11. Cliquez sur Accorder le consentement administrateur

Étape 2 : Configurer les revendications de jeton

Allez dans Configuration du jeton > Ajouter une revendication de groupes :

  • Sélectionnez Groupes de sécurité
  • Pour le Jeton d'ID, choisissez ID de groupe

Cela garantit que les appartenances aux groupes Azure AD sont incluses dans le jeton OIDC.

Étape 3 : Configurer Keycloak

  1. Connectez-vous à l'administration Keycloak à https://keycloak.<votre-domaine>/admin
  2. Sélectionnez le realm akko
  3. Allez dans Identity Providers > Add provider > OpenID Connect v1.0
  4. Configurez :
Champ Valeur
Alias azure-ad
Nom d'affichage Se connecter avec Microsoft
Endpoint de découverte https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration
Client ID <APPLICATION_CLIENT_ID>
Client Secret <CLIENT_SECRET_VALUE>
Scopes par défaut openid profile email
Mode de synchronisation force
Faire confiance à l'email Activé
  1. Cliquez sur Enregistrer

Étape 4 : Mapper les groupes Azure AD aux rôles AKKO

Sous la configuration du fournisseur d'identité, allez dans Mappers > Add mapper :

Champ Valeur
Nom azure-group-role-mapper
Type de Mapper Claim to Role
Claim groups
Valeur du Claim <AZURE_GROUP_OBJECT_ID> (ex. l'ID de "Data-Engineers")
Rôle akko-engineer

Répétez pour chaque groupe Azure AD que vous souhaitez mapper :

Groupe Azure AD Rôle AKKO Description
IT-Admins akko-admin Administrateurs de la plateforme
Data-Engineers akko-engineer Ingénieurs données
Business-Analysts akko-analyst Analystes métier
Compliance-Team akko-user Intendants de données
Management akko-viewer Accès en lecture seule

Automatisation avec values-enterprise.yaml

Les valeurs global.auth.ldap.roleMapping sont conçues pour la fédération LDAP. Pour le courtage OIDC, le mappage groupe-rôle est configuré dans l'interface d'administration Keycloak ou via l'API REST Admin. Envisagez de scripter cette configuration en utilisant le même modèle que configure-federation.sh.

2. Okta (courtage OIDC)

Étape 1 : Créer une application Okta

  1. Dans la console d'administration Okta, allez dans Applications > Create App Integration
  2. Choisissez OIDC - OpenID Connect et Web Application
  3. Configurez :
  4. Nom de l'intégration : AKKO Platform
  5. Type de grant : Authorization Code
  6. URI de redirection de connexion : https://keycloak.<votre-domaine>/realms/akko/broker/okta/endpoint
  7. URI de redirection de déconnexion : https://keycloak.<votre-domaine>/realms/akko/broker/okta/endpoint/logout_response
  8. Sous Assignments, assignez les utilisateurs ou groupes qui doivent accéder à AKKO
  9. Notez le Client ID et le Client Secret

Étape 2 : Configurer Keycloak

  1. Allez dans Identity Providers > Add provider > OpenID Connect v1.0
  2. Configurez :
Champ Valeur
Alias okta
Nom d'affichage Se connecter avec Okta
Endpoint de découverte https://<votre-org>.okta.com/.well-known/openid-configuration
Client ID <OKTA_CLIENT_ID>
Client Secret <OKTA_CLIENT_SECRET>
Scopes par défaut openid profile email groups
Mode de synchronisation force
Faire confiance à l'email Activé
  1. Cliquez sur Enregistrer

Étape 3 : Mapper les groupes Okta aux rôles AKKO

Ajoutez des mappers claim-to-role exactement comme décrit dans la section Azure AD ci-dessus, en utilisant le claim groups. Okta inclut les noms de groupes (pas les IDs) par défaut, vous pouvez donc faire correspondre directement les noms de groupes :

Valeur du Claim Rôle AKKO
Platform-Admins akko-admin
Data-Engineers akko-engineer
Analysts akko-analyst
Viewers akko-viewer

3. Google Workspace (courtage OIDC)

Étape 1 : Créer des identifiants OAuth dans Google Cloud

  1. Allez dans Google Cloud Console > APIs & Services > Credentials
  2. Cliquez sur Create Credentials > OAuth 2.0 Client ID
  3. Configurez :
  4. Type d'application : Application Web
  5. URI de redirection autorisée : https://keycloak.<votre-domaine>/realms/akko/broker/google/endpoint
  6. Notez le Client ID et le Client Secret
  7. Activez l'API Admin SDK si vous avez besoin de la synchronisation des groupes

Étape 2 : Configurer Keycloak

Keycloak dispose d'un fournisseur Google intégré :

  1. Allez dans Identity Providers > Add provider > Google
  2. Configurez :
Champ Valeur
Client ID <GOOGLE_CLIENT_ID>
Client Secret <GOOGLE_CLIENT_SECRET>
Scopes par défaut openid profile email
Faire confiance à l'email Activé
Domaine hébergé votre-entreprise.com (restreint à votre organisation)
  1. Cliquez sur Enregistrer

Étape 3 : Mapper les groupes Google aux rôles AKKO

Google Workspace n'inclut pas les groupes dans les jetons OIDC par défaut. Vous avez deux options :

Option A : Mapper de groupes Google (extension Keycloak)

Installez l'extension keycloak-google-groups et configurez-la comme mapper de fournisseur d'identité.

Option B : Attribution manuelle des rôles

Attribuez les rôles AKKO manuellement dans Keycloak après la première connexion des utilisateurs via Google. C'est plus simple mais ne passe pas à l'échelle pour les grandes organisations.

4. LDAP / Active Directory (fédération d'utilisateurs)

C'est l'approche recommandée pour les entreprises disposant d'un Active Directory ou d'un serveur OpenLDAP sur site. La fonctionnalité User Federation de Keycloak importe les utilisateurs et groupes directement dans la base de données Keycloak.

Étape 1 : Préparer votre fichier de valeurs

# values-enterprise.yaml
global:
  auth:
    mode: "enterprise"

    initialAdmin:
      enabled: true
      username: "admin-akko"
      email: "admin@corp.example.com"

    ldap:
      connectionUrl: "ldaps://ad.corp.example.com:636"
      bindDn: "cn=svc-akko,ou=service,dc=corp,dc=com"
      bindCredentialSecret: "akko-ldap-bind"
      usersDn: "ou=employees,dc=corp,dc=com"
      groupsDn: "ou=groups,dc=corp,dc=com"
      usernameLDAPAttribute: "sAMAccountName"   # "uid" pour OpenLDAP
      vendor: "ad"                               # "other" pour OpenLDAP
      roleMapping:
        akko-admin: ["IT-Admins", "Platform-Admins"]
        akko-engineer: ["Data-Engineers", "DevOps"]
        akko-analyst: ["Business-Analysts", "BI-Team"]
        akko-user: ["Compliance"]
        akko-viewer: ["Management"]

Étape 2 : Créer le secret de liaison LDAP

L'identifiant de liaison est stocké dans un Secret Kubernetes, pas dans les valeurs :

kubectl create namespace akko

kubectl create secret generic akko-ldap-bind \
  --from-literal=password='<MOT_DE_PASSE_LIAISON_LDAP>' \
  -n akko

Étape 3 : Déployer

helm upgrade --install akko helm/akko/ -n akko --create-namespace \
  --wait --wait-for-jobs --timeout 20m \
  -f helm/examples/values-dev.yaml \
  -f helm/examples/values-domain.yaml \
  -f values-enterprise.yaml \
  -f values-secrets.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-domain.json

Étape 4 : Configurer la fédération d'utilisateurs Keycloak (manuelle)

Si vous préférez configurer la fédération manuellement via l'interface d'administration Keycloak :

  1. Connectez-vous à https://keycloak.<votre-domaine>/admin
  2. Sélectionnez le realm akko
  3. Allez dans User federation > Add LDAP provider
  4. Remplissez les détails de connexion :
Champ Valeur Notes
Vendor Active Directory ou Other AD pour Microsoft AD, Other pour OpenLDAP
Connection URL ldaps://ad.corp.example.com:636 Utilisez ldaps:// pour TLS (port 636)
Bind DN cn=svc-akko,ou=service,dc=corp,dc=com Compte de service avec accès en lecture
Bind Credential <mot_de_passe> Le mot de passe de liaison LDAP
Users DN ou=employees,dc=corp,dc=com Où se trouvent les utilisateurs dans l'annuaire
Username LDAP attribute sAMAccountName uid pour OpenLDAP
RDN LDAP attribute cn
UUID LDAP attribute objectGUID entryUUID pour OpenLDAP
User object classes person, organizationalPerson, user inetOrgPerson pour OpenLDAP
Edit Mode READ_ONLY Keycloak ne peut pas modifier votre AD
Import Users Activé Synchroniser les utilisateurs vers la BDD Keycloak
  1. Cliquez sur Enregistrer puis Synchronize all users

Étape 5 : Configurer le mapper de groupes

Sous le fournisseur LDAP, allez dans Mappers > Add mapper :

Champ Valeur
Nom group-mapper
Type de Mapper group-ldap-mapper
Groups DN ou=groups,dc=corp,dc=com
Group Name LDAP Attribute cn
Group Object Classes group (groupOfUniqueNames pour OpenLDAP)
Membership LDAP Attribute member
Membership Attribute Type DN
Mode READ_ONLY

Cliquez sur Synchronize LDAP groups to Keycloak.

Étape 6 : Configurer les paramètres de synchronisation

Paramètre Valeur recommandée Description
Full Sync Period 300 (5 minutes) Intervalle de re-synchronisation complète en secondes
Changed Users Sync Period 60 (1 minute) Synchronisation incrémentale des utilisateurs modifiés
Batch Size 1000 Utilisateurs par lot de synchronisation
Pagination Activé Requis pour les annuaires volumineux

Étape 7 : Mapper les groupes LDAP aux rôles AKKO

Après la synchronisation des groupes, créez les mappages de rôles dans Keycloak :

  1. Allez dans Groups dans la barre latérale
  2. Pour chaque groupe LDAP (ex. IT-Admins) :
  3. Cliquez sur le groupe > Role mapping > Assign role
  4. Sélectionnez akko-admin (ou le rôle AKKO approprié)
  5. Répétez pour tous les groupes dans le tableau de correspondance

Vérification de l'intégration

Après avoir configuré votre IdP, vérifiez de bout en bout :

  1. Tester la connexion : Ouvrez https://cockpit.<votre-domaine> et cliquez sur Se connecter. Vous devriez voir une option de connexion pour votre IdP (ou être redirigé vers la page de connexion AD).

  2. Vérifier les rôles : Après la connexion, vérifiez le jeton de l'utilisateur : 

    # Dans un terminal JupyterHub
curl -s https://keycloak.<votre-domaine>/realms/akko/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer $JUPYTERHUB_API_TOKEN" | jq .

  3. Vérifier Keycloak : Dans l'administration Keycloak, allez dans Users et vérifiez que les utilisateurs fédérés apparaissent avec les bonnes appartenances de groupes et mappages de rôles.

  4. Tester le RBAC : Connectez-vous en tant qu'utilisateurs avec différents rôles et vérifiez qu'ils voient les données et services appropriés. Voir Administration RBAC pour la matrice complète des rôles.

Dépannage

Symptôme Cause Correctif
"Invalid redirect URI" à la connexion URI de redirection non concordante Vérifiez que l'URI de redirection dans votre IdP correspond exactement (y compris le suffixe /endpoint)
Les utilisateurs apparaissent mais n'ont aucun rôle Mappage groupe-rôle manquant Configurez les mappers de groupes et les attributions de rôles dans Keycloak
Connexion LDAP refusée Problème de pare-feu ou TLS Vérifiez la connectivité réseau depuis le pod Keycloak ; utilisez ldaps:// sur le port 636
"User not found" après synchronisation Users DN incorrect Vérifiez le chemin Users DN dans la configuration de votre fournisseur LDAP
Utilisateurs en double Lien de fédération manquant Supprimez les utilisateurs locaux en conflit avec les noms d'utilisateurs LDAP avant d'activer la fédération

Pour aller plus loin