A03 - Identité humaine

Groupe	Technologie	Statut	Service	Phase de la feuille de route	Contrats
A - Gouvernance, identité et sécurité	Keycloak (OIDC, SAML)	open source intégré	identity	1	common

Retour à l'index - English

Rôle et responsabilités

Authentification humaine, fédération SSO, MFA, groupes et correspondance des rôles.

Modèle de données

Tables (schéma eai, chaque table tenant porte tenant_id uuid NOT NULL avec une politique RLS sur current_setting('app.tenant_id', true)::uuid) : eai.memberships, eai.api_keys, eai.audit_events.

Endpoints API

• GET /v1/me
• GET /v1/members
• POST /v1/members
• PATCH /v1/members/{id}
• DELETE /v1/members/{id}
• GET /v1/api-keys
• POST /v1/api-keys
• DELETE /v1/api-keys/{id}
• POST /v1/api-keys/{id}/rotate

POST /v1/members HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: fr
Content-Type: application/json

{"user": "bob.martin", "email": "bob.martin@acme.example", "display_name": "Bob Martin", "role": "developer", "clearance": "internal"}

{
  "id": "21d243df-3f84-486e-a0a7-dd9dbb831a68",
  "tenant_id": "18de5695-21f9-4053-a4ea-beb4bf2a5932",
  "user_id": "cbb14d37-895e-4567-9a4d-67dee437dfce",
  "user": "bob.martin",
  "email": "bob.martin@acme.example",
  "display_name": "Bob Martin",
  "role": "developer",
  "clearance": "internal",
  "project_id": null,
  "created_at": "2026-10-30T02:35:52.697582+01:00"
}

Les erreurs utilisent l'enveloppe commune {"error": {"code", "message", "message_i18n", "details", "request_id"}} ; les listes sont paginées avec limit et cursor.

Fédération de l'annuaire et correspondances de groupes

Keycloak fédère l'annuaire d'entreprise ; la plateforme reste la seule source des accès, des clés et des quotas.

• LDAP / Active Directory : le realm deploy/keycloak/realm-enterprise-ai.json déclare le fournisseur de stockage corporate-ldap (lecture seule, vendor: ad, synchronisation périodique) et son group-ldap-mapper. Les valeurs de connexion sont des marqueurs ${EAI_LDAP_*} que kc.sh start --import-realm remplace par l'environnement du pod (deploy/keycloak/values.yaml) : EAI_LDAP_URL, EAI_LDAP_BIND_DN, EAI_LDAP_USERS_DN, EAI_LDAP_GROUPS_DN, et EAI_LDAP_BIND_CREDENTIAL lu dans le Secret keycloak-directory (clé ldap-bind-credential, synchronisée depuis OpenBao).
• Courtage Entra ID : fournisseur d'identité entra-id (OIDC, PKCE S256, signature vérifiée) avec EAI_ENTRA_TENANT_ID, EAI_ENTRA_CLIENT_ID et EAI_ENTRA_CLIENT_SECRET (Secret keycloak-directory, clé entra-client-secret). Le claim groups d'Entra est conservé dans l'attribut utilisateur entra_groups.
• Claims : le client scope eai-groups (scope par défaut de portal et cli) ajoute groups (noms des groupes Keycloak, groupes LDAP compris) et entra_groups au jeton d'accès.
• Correspondances (/v1/identity/group-mappings, portail Administration > Groupes d'annuaire) : par tenant, un groupe accorde un rôle sur un projet et, en option, un profil de quota (/v1/identity/quota-profiles). À chaque connexion OIDC qui porte un claim de groupes, le Control Plane crée l'adhésion et le quota de l'utilisateur (scope_type: user), puis les retire quand le groupe disparaît du jeton, quand la correspondance est modifiée ou supprimée. Ce qu'une correspondance a accordé est enregistré dans eai.group_mapping_grants ; une adhésion accordée à la main, ou attribuée ou modifiée par un administrateur après l'attribution, n'est jamais retirée. Modifier un profil de quota (PATCH) met à jour les quotas déjà accordés à partir de ce profil. Un jeton sans aucun claim de groupes ne change rien. Chaque attribution, retrait et modification est audité (identity.group_mapping.*, identity.quota_profile.*). EAI_OIDC_GROUP_SYNC=false désactive la synchronisation.
• Ce qui reste dans LiteLLM : seulement les providers et les modèles poussés par la plateforme (POST /v1/litellm/sync). Les clés et les quotas des équipes sont dans la plateforme, jamais dans LiteLLM.

Utilisation des SDK

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.identity.list_members()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.members.list();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.members().list();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Members.List(ctx)

Configuration

• Environnement : EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
• Valeurs Helm : controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config.

Contrôles de sécurité

• Authentification par JWT OIDC, clé API tenant avec scopes, ou mTLS SPIFFE ; le tenant est résolu depuis l'identifiant, jamais depuis le corps.
• Autorisation par décisions OpenFGA et OPA ; chaque mutation et décision écrit une ligne eai.audit_events chaînée par hash.
• Les secrets ne sont jamais renvoyés par l'API ; TLS partout ; les politiques réseau Cilium restreignent qui peut joindre le service.

Observabilité

• Métriques : eai_human_identity_requests_total, eai_human_identity_errors_total, eai_human_identity_latency_seconds (Prometheus).
• Traces : spans OpenTelemetry eai.members.* avec propagation W3C traceparent, spans IA envoyés à Opik.
• Actions d'audit : member.assign, member.update, member.remove, policy.evaluate.

Aspects FinOps

Le coût d'exploitation est imputé par tenant et projet via les labels des Usage Events et les requêtes de ressources Kubernetes ; pas de coût direct par appel.

Modes de défaillance et résilience

• Réplicas sans état derrière l'API Gateway, PostgreSQL HA pour l'état ; la sonde GET /readyz retire les pods défaillants.
• Système externe indisponible : échec fermé pour les décisions de sécurité, code d'erreur explicite, aucun contournement silencieux.

Adoption autonome (client d'un client)

Un client d'un client peut adopter cette brique seule avec le sous-client SDK Python client.identity (TS eai.members, Java client.members(), Go client.Members). Déploiement minimal : Control Plane API + PostgreSQL + Keycloak (ou clés API), le Control Plane charge tous les domaines de services/control-plane/src/eai/domains ; les composants optionnels du chart se coupent dans deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Tests d'acceptation

1. Un tenant ne peut ni lire ni modifier les ressources d'un autre tenant (test RLS).
2. Chaque mutation produit un événement d'audit vérifiable par GET /v1/audit/verify.
3. Les erreurs sont renvoyées en anglais et en français selon Accept-Language.

Preuves sur composants réels

Voir le guide du plan d'identité et de politiques : composants démarrés depuis les versions officielles (tools/iam/fetch.sh), tests services/control-plane/tests/test_iam_*.py.