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. L'esempio seguente mostra una risposta di un realm di dev; ogni ambiente configura la propria durata, quindi leggi expires_in da ogni risposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_in": 1800,
  "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. Il claim del tenant verificato nel token seleziona il tenant corrente. 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"

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

{
  "result": {
    "data": {
      "json": {
        "id": "123e4567-e89b-42d3-a456-426614174000",
        "externalId": "acme-prod",
        "name": "Acme Corp",
        "displayName": "Acme Corp",
        "branding": {
          "displayName": "Acme Corp",
          "logoUrl": null,
          "logoMarkUrl": null,
          "logoAlt": "Acme Corp",
          "accentColor": null,
          "coBranding": "kla-first"
        }
      }
    }
  }
}

Due header facoltativi hanno significati diversi:

Un soggetto senza un'appartenenza attiva riceve 403 quando tenta di selezionare un altro tenant:

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

{ "error": "Tenant access denied" }

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
  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

I realm di dev emettono attualmente access token con una durata di 30 minuti (expires_in: 1800). Leggi expires_in in ogni risposta del token, poiché ogni ambiente può configurare una durata diversa. Non fissare né memorizzare mai un token nella cache oltre la 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à.

Record di chiavi API ritirate

La revoca di una chiave API è permanente. Il segreto di supporto di una chiave API revocata non dispone di un'operazione di ripristino o rotazione. secrets.get con includeValue: true restituisce NOT_FOUND per un record revocato, archiviato, scaduto, assente o appartenente a un altro tenant. Le letture autorizzate dei metadati possono restituire dati del ciclo di vita di record revocati o scaduti; non restituiscono mai il valore del segreto. Crea una nuova chiave API e aggiorna l'integrazione.