Authentification

Chaque appel à l'API KLA Control Plane est authentifié par un jeton d'accès porteur OAuth 2.0 de courte durée et restreint à un seul tenant. Le KLA Control Plane est une couche de sécurité à l'exécution, d'audit et de gouvernance en place pour les agents IA d'entreprise ; son API permet d'enregistrer des agents, d'évaluer des politiques, d'acheminer des approbations et d'extraire des preuves. Cette page présente les deux types d'identifiants, la manière d'obtenir un jeton, la façon d'appeler l'API et les bonnes pratiques pour garder des identifiants au moindre privilège et régulièrement renouvelés.

Deux types d'identifiants

KLA émet des jetons par l'intermédiaire de son fournisseur d'identité, un service OpenID Connect (OIDC). Le flux à utiliser dépend de l'appelant.

La connexion interactive est celle qu'utilise la Console. Le navigateur exécute le flux OAuth 2.0 Authorization Code avec PKCE (Proof Key for Code Exchange), de sorte qu'aucun secret client ne se trouve jamais dans le code front-end. Vous n'avez pas à l'implémenter vous-même : elle est fournie avec la Console.

Les comptes de service sont ce qu'utilisent vos intégrations. Vous créez un client de compte de service par intégration, vous lui accordez les rôles minimaux dont il a besoin, puis vous échangez son client_id et son client_secret contre un jeton d'accès via le grant client credentials.

flowchart LR
  H["Humain dans la Console"] -->|"Connexion PKCE"| IDP["Fournisseur d'identité KLA"]
  M["Service backend"] -->|"client credentials"| IDP
  IDP -->|"jeton porteur"| API["API KLA Control Plane"]

Obtenir un jeton de compte de service

Échangez vos identifiants client auprès du point de terminaison de jeton du fournisseur d'identité. Le chemin du realm correspond à votre tenant : remplacez donc <tenant> par le slug de votre tenant.

curl -s -X POST \
  "https://auth.kla.digital/realms/<tenant>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=svc-claims-triage" \
  -d "client_secret=$KLA_CLIENT_SECRET"

La réponse est un objet JSON contenant le jeton d'accès porteur et sa durée de vie en secondes :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "agents:read decisions:write"
}

Conservez le jeton pour les appels qui suivent :

export KLA_ACCESS_TOKEN=$(curl -s -X POST \
  "https://auth.kla.digital/realms/<tenant>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=svc-claims-triage" \
  -d "client_secret=$KLA_CLIENT_SECRET" | jq -r .access_token)

Appeler l'API

Envoyez le jeton dans l'en-tête Authorization et indiquez votre tenant dans l'en-tête x-tenant-id. L'hôte de l'API est https://api.kla.digital. Utilisez cet aller-retour pour vérifier que votre jeton fonctionne :

curl -s https://api.kla.digital/v1/tenants.current \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-tenant-id: <tenant>"

Un appel réussi renvoie le tenant auquel le jeton est restreint :

{
  "tenant": { "id": "acme", "name": "Acme Corp", "region": "eu" }
}

La séquence ci-dessous illustre le chemin complet qu'un client machine suit à chaque cycle de jeton.

sequenceDiagram
  participant C as Service client
  participant IDP as Fournisseur d'identité KLA
  participant API as API KLA Control Plane
  C->>IDP: POST point de terminaison de jeton avec client credentials
  IDP-->>C: access_token et expires_in
  C->>API: GET v1/tenants.current avec porteur et x-tenant-id
  API-->>C: 200 charge utile du tenant
  Note over C,IDP: En cas de 401 expiré, demander un nouveau jeton et réessayer

Durée de vie et renouvellement des jetons

Les jetons d'accès sont de courte durée, généralement cinq minutes (expires_in: 300). Cela limite le rayon d'impact d'un jeton compromis. Ne figez pas et ne mettez pas en cache un jeton au-delà de son expiration.

• Les comptes de service demandent simplement un nouveau jeton au point de terminaison de jeton lorsque le jeton courant approche de son expiration. Le grant client credentials n'émet pas de jeton de rafraîchissement : c'est la réexécution de l'échange qui fait office de rafraîchissement.
• Les sessions interactives de la Console utilisent un jeton de rafraîchissement distinct et à durée de vie plus longue, géré par le navigateur, pour obtenir silencieusement de nouveaux jetons d'accès.
• Un 401 Unauthorized renvoyé par l'API signifie que le jeton est expiré ou invalide. Demandez un nouveau jeton et réessayez une fois.

Portées et rôles au moindre privilège

Chaque jeton porte les rôles de son principal, et l'API autorise chaque requête en fonction de ceux-ci. N'accordez à un compte de service que les rôles requis par sa mission :

• Un agent qui émet de la télémétrie a besoin d'un accès en écriture aux traces, pas de l'écriture de politiques.
• Une automatisation d'approbations a besoin de decisions:read et decisions:write, pas de droits de déploiement d'agents.
• Un exporteur de preuves en lecture seule a besoin d'un accès en lecture aux preuves et de rien d'autre.

Créez un compte de service par intégration, afin de pouvoir révoquer ou redéfinir la portée d'un seul appelant sans perturber les autres. Les rôles se gèrent dans l'Agent Registry et dans les paramètres du tenant de la Console.

Renouveler les secrets de compte de service

Un client_secret est un identifiant à longue durée de vie : traitez-le comme un mot de passe de base de données. Renouvelez-le selon un calendrier régulier et immédiatement en cas de suspicion d'exposition.

Stockez et renouvelez les secrets de compte de service dans le Secrets Vault, la surface de la Console dédiée au stockage sensible. Générez-y un nouveau secret, déployez-le sur votre intégration, vérifiez que les nouveaux jetons sont bien émis, puis retirez l'ancien secret. Le Secrets Vault prend en charge le chevauchement de secrets pendant une rotation, ce qui vous permet de passer à la nouvelle version sans aucune interruption de service.