OAuth für KI-Agenten: Sicheres Handeln im Nutzerauftrag

Ihr Agent muss den Kalender eines Kunden lesen, eine Nachricht von dessen Konto senden oder ein Ticket unter dessen Namen erstellen. Ein gemeinsames Dienstkonto mit weitreichendem Zugriff ist dafür die schnelle, aber falsche Lösung: Aktionen erscheinen nur als „die Integration“, niemand kann nachvollziehen, welcher Benutzer sie ausgelöst hat, und kompromittierte Zugangsdaten gefährden alle Konten. Verwenden Sie stattdessen delegierte OAuth-2.0-Autorisierung: Benutzer gewähren widerrufbare, bereichsspezifische Tokens, der Agent agiert in ihrem Auftrag, und der Audit-Trail bleibt nachvollziehbar.

Apidog noch heute ausprobieren

Dieser Leitfaden zeigt, welcher OAuth-Flow zu Agenten passt, wie Sie Scopes und Tokens verwalten, wie Sie Ablauf und Widerruf behandeln und wie Sie den vollständigen Ablauf ohne Produktionskonto testen. Wenn Sie noch zwischen schlüsselbasierter und delegierter Authentifizierung abwägen, beginnen Sie mit dem Vergleich API-Schlüssel vs. OAuth. Apidog hilft dabei, auch Fehlerpfade vor dem Produktionseinsatz zu simulieren.

Dienstkonto oder delegierter Zugriff

Wählen Sie das Modell anhand des Ressourcenbesitzes:

• Dienstkonto: Die eigene Identität des Agenten, geeignet für Ihre Datenbank, interne Dienste und Infrastrukturjobs. Begrenzen Sie die Berechtigungen strikt und rotieren Sie Schlüssel regelmäßig. Siehe API-Schlüssel mit geringsten Rechten für Agenten.
• Delegierter Zugriff: Der Agent handelt als konkreter Benutzer und nur innerhalb dessen Berechtigungen. Das ist erforderlich, wenn Daten anderen Personen gehören.

Delegierter Zugriff bietet drei entscheidende Eigenschaften:

1. Benutzer sehen, welche Berechtigungen sie erteilt haben.
2. Benutzer können den Zugriff widerrufen.
3. Jede Aktion bleibt einer Benutzeridentität zugeordnet.

Vermeiden Sie ein organisationsweites Dienstkonto, das „als Benutzer“ handelt. Ein einziges Leck öffnet sonst alle Konten, pro Benutzer ist kein Widerruf möglich, und Ihr Audit-Trail ist unzuverlässig.

Den passenden OAuth-Flow wählen

OAuth 2.0 definiert mehrere Grant Types. Für Agenten sind vor allem diese relevant:

Autorisierungscode mit PKCE

Der Autorisierungscode-Grant ist der Standard für delegierten Benutzerzugriff:

1. Ein Benutzer öffnet den Browser und genehmigt angeforderte Scopes.
2. Ihr Dienst tauscht den Autorisierungscode gegen Tokens aus.
3. Der Agent verwendet später den resultierenden Refresh-Token im Hintergrund.

PKCE schützt den Code-Austausch und ist laut OAuth 2.0 Security Best Current Practice für alle Client-Typen empfohlen. Details stehen in der OAuth-2.0-Spezifikation.

Der entscheidende Architekturpunkt: Die Zustimmung geschieht einmalig zur Verbindungszeit. Der Agent führt den Browser-Flow nie selbst aus.

Client Credentials

Der Client-Credentials-Flow ist für Maschine-zu-Maschine-Kommunikation ohne Benutzer gedacht. Nutzen Sie ihn für Dienstkonten, niemals um als Benutzer zu handeln.

Geräteautorisierungs-Grant

Für Headless-Agenten oder CLI-Umgebungen: Der Agent zeigt einen Code an, der Benutzer bestätigen die Zustimmung auf einem anderen Gerät mit Browser.

Token-Austausch

RFC 8693 erlaubt den Austausch eines Tokens gegen ein stärker eingeschränktes Token. Das ist sinnvoll für Sub-Agenten: Statt den ursprünglichen Benutzer-Grant weiterzugeben, erhält jeder Sub-Agent nur ein Token für seine konkrete Aufgabe. Das ergänzt die Grenzen aus dem Beitrag zum Multi-Agenten-Handoff.

Scopes pro Agent begrenzen

Scopes sind der Sicherheitsgewinn von delegiertem Zugriff. Fordern Sie nie pauschal alles an.

• Fordern Sie nur die Scopes an, die ein Agent benötigt. Ein Kalenderagent braucht Kalender-Schreibzugriff, aber keine E-Mails, Kontakte oder Dateien.
• Fordern Sie Berechtigungen inkrementell an: zunächst das Minimum, weitere Scopes erst bei einer konkreten Benutzeraktion.
• Geben Sie jedem Agenten eigene Tokens mit eigenen Scopes. Ein kompromittierter Forschungsagent darf keine Rückerstattungen auslösen.
• Starten Sie mit Lese-Scopes. Schreibrechte brauchen eine explizite Eskalation und bei riskanten Aktionen eine zusätzliche Genehmigungsschranke.

Wie Anbieter Scopes modellieren, erläutert OAuth 2 Scopes. Ergänzen Sie Schreibzugriffe mit den in KI-Agenten-Guardrails beschriebenen Freigaben.

Tokens speichern, aktualisieren und widerrufen

Tokens sind Zugangsdaten. Behandeln Sie sie entsprechend.

Speicherung

• Verschlüsseln Sie Refresh-Tokens im Ruhezustand und pro Benutzer.
• Schreiben Sie Tokens nie in Logs, Prompts oder Traces.
• Lassen Sie das Modell niemals Tokens sehen.
• Redigieren Sie Secrets an der Systemgrenze, nicht erst beim späteren Lesen von Logs. Siehe Tracing von Agenten-Tool-Aufrufen.

Aktualisierung

Access-Tokens sind kurzlebig. Ein Token-Manager vor dem HTTP-Client sollte Tokens kurz vor Ablauf erneuern und einen 401-Fehler genau einmal erneut versuchen:

class TokenManager:
    def __init__(self, store, provider):
        self.store, self.provider = store, provider

    def access_token(self, user_id, agent_scope):
        rec = self.store.get(user_id, agent_scope)
        if rec.expires_in() > 60:
            return rec.access_token
        fresh = self.provider.refresh(rec.refresh_token, scope=agent_scope)
        self.store.save(user_id, agent_scope, fresh)   # Rotation: speichere das neue Refresh-Token
        return fresh.access_token

Beachten Sie zwei Regeln:

1. Viele Anbieter rotieren Refresh-Tokens. Speichern Sie das neue Token sofort, sonst sperren Sie Benutzer aus.
2. Serialisieren Sie Refreshes pro Benutzer. Zwei parallele Aktualisierungen können bei rotierenden Tokens gegeneinander verlieren.

Widerruf und Fehler

Behandeln Sie 401 und 403 als endgültig:

• 401: Token ist abgelaufen, ungültig oder widerrufen.
• 403: Ein erforderlicher Scope fehlt.
• invalid_grant: Der Refresh-Grant ist nicht mehr gültig.

Wiederholen Sie diese Fehler nicht endlos. Stoppen Sie den Lauf und melden Sie klar, welcher Benutzer und welcher Scope betroffen ist. Geeignete Fehlerantworten beschreibt API-Fehlerdesign für Agenten.

Zustimmung von Laufzeit trennen

Agenten laufen häufig unbeaufsichtigt, OAuth-Zustimmung benötigt dagegen einen Menschen. Lösen Sie das durch eine klare Trennung:

• Verbindungszeit: Eine Person autorisiert die Integration im Browser; Ihr System speichert den Refresh-Token.
• Laufzeit: Der Agent verwendet die bestehende Berechtigung im Hintergrund.

Achten Sie auf zwei Grenzen:

• Grants können nach längerer Inaktivität oder durch Richtlinien ablaufen. Erkennen Sie das, stoppen Sie den Lauf und fordern Sie eine erneute Verbindung an.
• Ein Agent darf seine eigenen Scopes nicht eskalieren. Fehlt ein Scope, muss er explizit erneut um Zustimmung bitten.

Für Aktionen mit hoher Auswirkung reicht ein Token allein nicht aus. Das Token beantwortet, ob ein Agent darf; eine Freigabestufe beantwortet, ob er sollte.

Den OAuth-Pfad mit Mocks testen

Testen Sie diese fünf Fälle in CI:

1. Glücklicher Pfad: Gültiger Access-Token, erfolgreicher API-Aufruf.
2. **Abgelaufener [REDACTED CREDENTIAL] API liefert 401, der Manager aktualisiert, ein Wiederholungsversuch ist erfolgreich.
3. **Widerrufener [REDACTED CREDENTIAL] Refresh liefert invalid_grant; der Agent stoppt und meldet den Fehler.
4. Unzureichender Scope: API liefert 403; der Agent wiederholt nicht und nennt den fehlenden Scope.
5. Gleichzeitige Aktualisierung: Zwei Anfragen für denselben Benutzer führen zu genau einem Refresh.

Definieren Sie in Apidog den Token-Endpunkt und geschützte APIs als Mocks. So simulieren Sie auch Fehler-Bodies ohne echte Anbieterzugänge. Weitere Praxis finden Sie unter Agenten gegen Mocks statt Produktion ausführen und im OAuth-2-API-Testleitfaden.

Drei typische Integrationen

Kalenderassistent

Der Agent liest Verfügbarkeiten und bucht Termine für einen Benutzer.

• Delegierter Zugriff
• Zwei minimale Kalender-Scopes
• Browser-Zustimmung zur Verbindungszeit
• Hintergrundausführung zur Laufzeit

Wichtigster Fehlerfall: Der Benutzer trennt die Integration. Der nächtliche Job muss den Widerruf erkennen und stoppen, statt einen toten Grant wiederholt zu verwenden.

Support-Agent für einen gemeinsamen Posteingang

Bei einer Teamressource kann eine Bot-Identität mit eigenen Scopes passend sein. Protokollieren Sie zusätzlich, welcher Mensch den Lauf ausgelöst hat. So bleibt die Zuordnung erhalten, ohne vorzugeben, der Agent sei eine konkrete Person.

Interner Betriebsagent

Startet der Agent Dienste neu oder liest eigene Infrastruktur-Dashboards, sind keine Benutzerdaten beteiligt. Nutzen Sie ein eng begrenztes Dienstkonto und investieren Sie in Rotation und Begrenzung der Angriffsfläche.

Die Regel lautet: Gehören die Daten jemandem, der Ihren Zugriff plausibel widerrufen möchte, verwenden Sie delegierte Authentifizierung. Gehören die Daten Ihnen, verwenden Sie ein Dienstkonto.

Benutzeridentität und Auftraggeber protokollieren

Delegierte Authentifizierung beantwortet: „In wessen Auftrag handelt der Agent?“ Sie beantwortet nicht: „Wer hat diesen Lauf angefordert?“

Protokollieren Sie deshalb neben jeder Aktion:

• Benutzer-ID
• Agentenname
• verwendeten Scope
• Token-Identifikator, niemals das Token
• auslösende Person oder Aufgabe

Eine Arbeitsverwaltungsebene kann diese Identitäten getrennt halten. Eine Sharkly-Aufgabe erfasst beispielsweise die verantwortliche Person neben dem ausführenden Agenten oder der Crew. Die Sharkly-Dokumentation beschreibt dieses Modell detailliert.

Das Modell darf keine Zugangsdaten halten

Eine Regel verhindert einen Großteil der Authentifizierungsvorfälle: Das Modell sieht niemals Tokens.

Der Executor injiziert das Token erst auf HTTP-Ebene, nachdem das Modell ein Tool und dessen Argumente gewählt hat:

• Tool-Schemas haben keinen Token-Parameter.
• Prompts enthalten keine Zugangsdaten.
• Tool-Antworten entfernen Authorization-Header.
• Der Executor bestimmt aus dem Laufkontext, für welchen Benutzer das passende Token verwendet wird.

Modellkontext kann in Traces, Zusammenfassungen, Fehlern oder Antworten erscheinen. Ein Token im Kontext ist damit ein potenzielles Leck. Das gilt ebenso für die Benutzerwahl: Das Modell sollte nicht entscheiden, als welcher Benutzer eine Aktion ausgeführt wird.

Checkliste

• Delegierten Zugriff für Benutzerdaten verwenden; Dienstkonten nur für eigene Ressourcen.
• Autorisierungscode mit PKCE zur Verbindungszeit einsetzen; Geräte-Grant für Headless-Systeme.
• Scopes pro Agent minimal halten und inkrementell erweitern.
• Sub-Agenten ausgetauschte Tokens geben, nie Kopien des Benutzer-Grants.
• Refresh-Tokens verschlüsseln und aus Prompts, Logs und Traces fernhalten.
• Refreshes über einen pro Benutzer serialisierten Token-Manager steuern.
• 401 und 403 endgültig behandeln und Benutzer sowie Scope in der Fehlermeldung nennen.
• Abgelaufene Grants erkennen und erneute Zustimmung anfordern.
• Riskante Aktionen zusätzlich zum Token durch Freigaben schützen.
• Alle fünf Authentifizierungsszenarien mit Mocks in CI testen.

Delegierte Authentifizierung erfordert mehr Aufwand als ein gemeinsamer Schlüssel, liefert aber Widerrufbarkeit und einen ehrlichen Audit-Trail. Laden Sie Apidog herunter, um Token-Flows und Fehlerfälle zu testen, bevor ein Agent unbeaufsichtigt handelt.

Häufig gestellte Fragen

Kann ein Agent den OAuth-Zustimmungsflow selbst abschließen?

Nein. Zustimmung erfordert eine Person, die bewusst über Berechtigungen entscheidet. Lassen Sie Benutzer einmalig über einen normalen Browser-Flow autorisieren und verwenden Sie danach den resultierenden Grant.

Sollte jeder Agent einen eigenen OAuth-Client haben?

Verwenden Sie getrennte Clients pro Produktintegration und getrennte Tokens pro Agent. Idealerweise leiten Sie diese über Token-Austausch ab. Separate Clients sind besonders sinnvoll bei clientbezogenen Ratenlimits oder unabhängigem Widerruf.

Was passiert, wenn ein rotierter Refresh-Token nicht gespeichert wird?

Der Benutzer wird ausgesperrt und muss die Integration erneut verbinden. Speichern Sie den neuen Refresh-Token in derselben Transaktion, die den alten verwendet, und serialisieren Sie Aktualisierungen pro Benutzer.

Ist es sicher, dem Modell einen Access-Token zu zeigen?

Nein. Tokens gehören ausschließlich in die HTTP-Schicht des Executors. Alles im Modellkontext kann in Traces, Zusammenfassungen oder Antworten landen.

Wie prüfe ich, welcher Agent was getan hat?

Protokollieren Sie Benutzer-ID, Agentenname, Scope und Token-Identifikator für jeden Aufruf — niemals das Token selbst. Weitere Strukturhinweise finden Sie im Beitrag zum Tracing von Agenten-Tool-Aufrufen.

Was ist, wenn der Anbieter keinen Token-Austausch unterstützt?

Speichern Sie getrennte Grants pro Agent, sofern der Anbieter mehrere zulässt. Alternativ erzwingen Sie die Scope-Begrenzung in einem eigenen Gateway, das nicht erlaubte Agentenoperationen blockiert, bevor sie Ihr Netzwerk verlassen.