Autenticazione

Ogni chiamata all'API del KLA Control Plane viene autenticata con un bearer access token OAuth 2.0 di breve durata ed è circoscritta a un singolo tenant. Il KLA Control Plane è un livello di sicurezza, audit e governance a tempo di esecuzione, applicato in loco (govern-in-place), per gli agenti AI aziendali; la sua API è il modo in cui registri gli agenti, valuti le policy, instradi le approvazioni ed estrai le evidenze. Questa pagina spiega i due tipi di credenziali, come ottenere un token, come chiamare l'API e come mantenere le credenziali secondo il principio del privilegio minimo e con rotazione regolare.

Due tipi di credenziali

KLA emette i token tramite il proprio identity provider, un servizio OpenID Connect (OIDC). Il flusso da utilizzare dipende da chi effettua la chiamata.

L'accesso interattivo è ciò che usa la Console. Il browser esegue il flusso OAuth 2.0 Authorization Code con PKCE (Proof Key for Code Exchange), così nessun client secret risiede mai nel codice del front-end. Non devi implementarlo tu: è già incluso nella Console.

Gli account di servizio sono ciò che usano le tue integrazioni. Crei un client di tipo account di servizio per ogni integrazione, gli assegni i ruoli minimi necessari e scambi il suo client_id e client_secret con un access token tramite il grant client credentials.

flowchart LR
  H["Persona nella Console"] -->|"accesso PKCE"| IDP["KLA identity provider"]
  M["Servizio di backend"] -->|"client credentials"| IDP
  IDP -->|"bearer token"| API["KLA Control Plane API"]

Ottenere un token per un account di servizio

Scambia le tue client credentials presso l'endpoint dei token dell'identity provider. Il percorso del realm corrisponde al tuo tenant, quindi sostituisci <tenant> con lo slug del tuo 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 risposta è un oggetto JSON che contiene il bearer access token e la sua durata in secondi:

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

Cattura il token per le chiamate che seguono:

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)

Chiamare l'API

Invia il token nell'header Authorization e indica il tuo tenant nell'header x-tenant-id. L'host dell'API è https://api.kla.digital. Usa questa chiamata di andata e ritorno per verificare che il tuo token funzioni:

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

Una chiamata riuscita restituisce il tenant a cui il token è circoscritto:

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

La sequenza seguente mostra l'intero percorso che un client macchina segue a ogni ciclo del token.

sequenceDiagram
  participant C as Servizio client
  participant IDP as KLA identity provider
  participant API as KLA Control Plane API
  C->>IDP: POST all'endpoint dei token con le client credentials
  IDP-->>C: access_token e expires_in
  C->>API: GET v1/tenants.current con bearer e x-tenant-id
  API-->>C: 200 payload del tenant
  Note over C,IDP: In caso di 401 scaduto, richiedi un nuovo token e riprova

Durata e rinnovo del token

Gli access token hanno breve durata, tipicamente cinque minuti (expires_in: 300). Questo limita il raggio d'azione di un token compromesso. Non fissare né mettere in cache un token oltre la sua scadenza.

• Gli account di servizio richiedono semplicemente un nuovo token all'endpoint dei token quando quello corrente si avvicina alla scadenza. Il grant client credentials non rilascia un refresh token; il rinnovo consiste nel rieseguire lo scambio.
• Le sessioni interattive della Console utilizzano un refresh token separato e a durata più lunga, gestito dal browser per ottenere silenziosamente nuovi access token.
• Un 401 Unauthorized da parte dell'API significa che il token è scaduto o non valido. Richiedi un nuovo token e riprova una volta.

Scope e ruoli a privilegio minimo

Ogni token porta con sé i ruoli del proprio principal e l'API autorizza ogni richiesta in base ad essi. Concedi a un account di servizio solo i ruoli richiesti dal suo compito:

• Un agente che emette telemetria necessita dell'accesso in scrittura alle tracce, non della creazione di policy.
• Un'automazione delle approvazioni necessita di decisions:read e decisions:write, non dei diritti di deployment degli agenti.
• Un esportatore di evidenze in sola lettura necessita dell'accesso in lettura alle evidenze e nient'altro.

Crea un account di servizio per ogni integrazione, così da poter revocare o ridefinire gli scope di un singolo chiamante senza interrompere gli altri. I ruoli si gestiscono nell'Agent Registry e nelle impostazioni del tenant della Console.

Rotazione dei segreti degli account di servizio

Un client_secret è una credenziale a lunga durata: trattalo come la password di un database. Ruotalo a cadenza regolare e immediatamente in caso di sospetta esposizione.

Memorizza e ruota i segreti degli account di servizio nel Secrets Vault, la superficie della Console dedicata all'archiviazione di dati sensibili. Genera lì un nuovo segreto, distribuiscilo alla tua integrazione, verifica che i nuovi token vengano emessi correttamente e quindi ritira il vecchio segreto. Il Secrets Vault supporta segreti sovrapposti durante una rotazione, così da poter procedere con zero tempi di inattività.