Authentifizierung

Jeder Aufruf der KLA Control Plane API wird mit einem kurzlebigen OAuth-2.0-Bearer-Access-Token authentifiziert und auf einen einzelnen Mandanten beschränkt. Die KLA Control Plane ist eine govern-in-place-Schicht für Laufzeitsicherheit, Auditierung und Governance von KI-Agenten im Unternehmen. Über ihre API registrieren Sie Agenten, werten Richtlinien aus, leiten Genehmigungen weiter und rufen Nachweise ab. Diese Seite erläutert die beiden Anmeldedatentypen, wie Sie ein Token erhalten, wie Sie die API aufrufen und wie Sie Anmeldedaten mit minimalen Rechten ausstatten und rotieren.

Zwei Anmeldedatentypen

KLA stellt Token über seinen Identity Provider aus, einen OpenID-Connect-(OIDC)-Dienst. Welchen Flow Sie verwenden, hängt davon ab, wer den Aufruf tätigt.

Die interaktive Anmeldung ist das, was die Console verwendet. Der Browser führt den OAuth-2.0-Authorization-Code-Flow mit PKCE (Proof Key for Code Exchange) aus, sodass niemals ein Client Secret im Frontend-Code liegt. Sie implementieren das nicht selbst; es ist Teil der Console.

Servicekonten sind das, was Ihre Integrationen verwenden. Sie erstellen pro Integration einen Servicekonto-Client, geben ihm die minimal erforderlichen Rollen und tauschen seine client_id und sein client_secret über den Client-Credentials-Grant gegen ein Access-Token.

flowchart LR
  H["Mensch in der Console"] -->|"PKCE-Anmeldung"| IDP["KLA Identity Provider"]
  M["Backend-Dienst"] -->|"Client-Credentials"| IDP
  IDP -->|"Bearer-Token"| API["KLA Control Plane API"]

Ein Servicekonto-Token erhalten

Tauschen Sie Ihre Client-Anmeldedaten am Token-Endpunkt des Identity Providers ein. Der Realm-Pfad ist Ihr Mandant, ersetzen Sie daher <tenant> durch Ihren Mandanten-Slug.

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"

Die Antwort ist ein JSON-Objekt, das das Bearer-Access-Token und seine Gültigkeitsdauer in Sekunden enthält:

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

Erfassen Sie das Token für die folgenden Aufrufe:

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)

Die API aufrufen

Senden Sie das Token im Authorization-Header und benennen Sie Ihren Mandanten im x-tenant-id-Header. Der API-Host ist https://api.kla.digital. Verwenden Sie diesen Roundtrip, um zu bestätigen, dass Ihr Token funktioniert:

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

Ein erfolgreicher Aufruf gibt den Mandanten zurück, auf den das Token beschränkt ist:

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

Die folgende Abfolge zeigt den vollständigen Pfad, den ein Maschinen-Client bei jedem Token-Zyklus durchläuft.

sequenceDiagram
  participant C as Client-Dienst
  participant IDP as KLA Identity Provider
  participant API as KLA Control Plane API
  C->>IDP: POST Token-Endpunkt mit Client-Credentials
  IDP-->>C: access_token plus expires_in
  C->>API: GET v1/tenants.current mit Bearer plus x-tenant-id
  API-->>C: 200 Mandanten-Payload
  Note over C,IDP: Bei 401 abgelaufen ein frisches Token anfordern und erneut versuchen

Token-Lebensdauer und Erneuerung

Access-Token sind kurzlebig, typischerweise fünf Minuten (expires_in: 300). Das begrenzt den Schadensradius eines geleakten Tokens. Pinnen oder cachen Sie ein Token nicht über seinen Ablauf hinaus.

• Servicekonten fordern einfach ein neues Token vom Token-Endpunkt an, wenn das aktuelle dem Ablauf nahekommt. Der Client-Credentials-Grant stellt kein Refresh-Token aus; die erneute Ausführung des Austauschs ist die Erneuerung.
• Interaktive Console-Sitzungen verwenden ein separates, langlebigeres Refresh-Token, das vom Browser verwaltet wird, um stillschweigend neue Access-Token zu erhalten.
• Ein 401 Unauthorized von der API bedeutet, dass das Token abgelaufen oder ungültig ist. Fordern Sie ein frisches Token an und versuchen Sie es einmal erneut.

Scopes und Rollen mit minimalen Rechten

Jedes Token trägt die Rollen seines Principals, und die API autorisiert jede Anfrage anhand dieser Rollen. Geben Sie einem Servicekonto nur die Rollen, die seine Aufgabe erfordert:

• Ein Agent, der Telemetrie aussendet, benötigt Schreibzugriff auf Traces, nicht die Erstellung von Richtlinien.
• Eine Genehmigungs-Automatisierung benötigt decisions:read und decisions:write, nicht die Rechte zum Deployment von Agenten.
• Ein schreibgeschützter Nachweis-Exporter benötigt Lesezugriff auf Nachweise und sonst nichts.

Erstellen Sie pro Integration ein Servicekonto, damit Sie einen einzelnen Aufrufer widerrufen oder neu zuschneiden können, ohne andere zu stören. Rollen werden im Agent Registry und in den Mandanteneinstellungen der Console verwaltet.

Servicekonto-Secrets rotieren

Ein client_secret ist eine langlebige Anmeldeinformation: Behandeln Sie es wie ein Datenbankpasswort. Rotieren Sie es nach einem festen Zeitplan und sofort bei jedem vermuteten Leck.

Speichern und rotieren Sie Servicekonto-Secrets im Secrets Vault, der Console-Oberfläche für sensible Speicherung. Erzeugen Sie dort ein neues Secret, verteilen Sie es an Ihre Integration, bestätigen Sie, dass neue Token korrekt ausgestellt werden, und nehmen Sie dann das alte Secret außer Betrieb. Der Secrets Vault unterstützt überlappende Secrets während einer Rotation, sodass Sie ohne Ausfallzeit umstellen können.