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. Die schnelle Version besteht darin, ein einziges Dienstkonto mit weitreichendem Zugriff zu halten und darüber zu agieren. Jede Aktion erscheint als „die Integration“, niemand kann erkennen, welcher Benutzer was ausgelöst hat, und eine kompromittierte Zugangsdatensammlung legt jedes Konto offen, auf das Sie zugreifen.

Die korrekte Version ist die delegierte Autorisierung: Der Benutzer gewährt Ihrem Agenten ein bereichsspezifisches, widerrufbares Token, der Agent agiert als dieser Benutzer, und der Audit-Trail benennt sie. Dafür wurde OAuth 2.0 entwickelt. Was es für Agenten schwierig macht, ist, dass OAuth einen Browser und eine anwesende Person zum Klicken auf „Zulassen“ voraussetzt, während Agenten um 3 Uhr morgens im Hintergrund laufen.

Dieser Leitfaden behandelt, welcher OAuth-Flow zu einem Agenten passt, wie Tokens bereichsspezifisch festgelegt und gespeichert werden, was bei der Aktualisierung und dem Widerruf zu tun ist und wie der gesamte Pfad ohne ein aktives Konto getestet werden kann. Wenn Sie noch zwischen schlüsselbasierter und delegierter Authentifizierung wählen, ist unser Vergleich von API-Schlüsseln und OAuth der richtige Ausgangspunkt.

Apidog hilft bei dem Teil, den Teams unterschätzen: jeden Zweig des Ablaufs zu trainieren, einschließlich Ablauf und Widerruf, bevor ein Agent sie in der Produktion trifft.

Dienstkonto oder delegierter Zugriff

Wählen Sie bewusst, denn die beiden Modelle versagen unterschiedlich.

Ein Dienstkonto ist die eigene Identität Ihres Agenten mit eigenen Berechtigungen. Es eignet sich für Aufgaben, die der Agent in Ihrem Namen ausführt: das Lesen Ihrer eigenen Datenbank, das Aufrufen Ihrer internen Dienste, das Ausführen geplanter Aufgaben in Ihrer Infrastruktur. Schränken Sie den Umfang stark ein, wie in unserem Beitrag über API-Schlüssel mit geringsten Rechten für Agenten, und rotieren Sie ihn.

Delegierter Zugriff bedeutet, dass der Agent als ein bestimmter Benutzer agiert, mit den Berechtigungen dieses Benutzers und nicht mehr. Dies ist immer dann erforderlich, wenn die Daten jemand anderem gehören. Drei Eigenschaften machen den zusätzlichen Aufwand lohnenswert: Der Benutzer kann sehen, was gewährt wurde, der Benutzer kann es widerrufen, und jede Aktion trägt seine Identität im Protokoll.

Der zu vermeidende Fehlermodus ist ein Dienstkonto mit organisationsweitem Zugriff, das verwendet wird, um „als“ Benutzer zu agieren. Es funktioniert zwar, bedeutet aber, dass eine einzige durchgesickerte Zugangsdatensammlung jeden offenlegt, ohne Widerruf pro Benutzer und ohne ehrlichen Audit-Trail.

Welcher Flow passt zu einem Agenten

OAuth 2.0 definiert mehrere Grant Types (Gewährungstypen), und nur wenige sind hier sinnvoll. Die OAuth 2.0-Spezifikation enthält den vollständigen Satz; dies sind die, die Sie verwenden werden.

Autorisierungscode mit PKCE. Der Standard-Flow, um als Benutzer zu agieren. Der Benutzer wird zum Anbieter umgeleitet, genehmigt die Scopes, und Ihr Dienst tauscht den Code gegen Tokens aus. PKCE schützt den Austausch und ist nun die Standardempfehlung für jeden Client-Typ, gemäß der OAuth 2.0 Security Best Current Practice. Unser Leitfaden zum Autorisierungscode-Grant behandelt die Mechaniken Schritt für Schritt.

Der agentspezifische Punkt: Dieser Flow läuft einmal, mit anwesendem Menschen, zur Verbindungszeit. Der Agent führt ihn niemals aus. Er verwendet den Refresh-Token, den der Flow erzeugt hat. Trennen Sie diese beiden Momente in Ihrem Design, und die meisten Schwierigkeiten verschwinden.

Client-Anmeldeinformationen (Client Credentials). Maschine-zu-Maschine, kein Benutzer beteiligt. Korrekt für Dienstkonten und falsch, um als Benutzer zu agieren, da kein Benutzer zur Zustimmung vorhanden ist.

Geräteautorisierungs-Grant. Für Agenten auf Maschinen ohne Browser. Der Benutzer erhält einen Code und genehmigt ihn auf seinem Telefon. Nützlich für CLI-Agenten und Headless-Umgebungen.

Token-Austausch. RFC 8693 ermöglicht es einem Dienst, ein Token gegen ein spezifischeres einzutauschen. So geben Sie einem Sub-Agenten ein Token, das auf einen Scope für eine Aufgabe beschränkt ist, abgeleitet vom umfassenderen Grant des Benutzers, ohne ihm das Original auszuhändigen. Wenn Sie Multi-Agenten-Systeme betreiben, ist dies der Mechanismus, der agentenspezifische Anmeldeinformationen praktisch macht, und er passt zu den Grenzregeln in unserem Beitrag zum Multi-Agenten-Handoff.

Bereichsspezifisch und pro Agent

Scopes sind der Bereich, in dem delegierter Zugriff seinen Wert beweist und wo die meisten Implementierungen faul werden, indem sie alles anfordern, was die App jemals benötigen könnte.

Fordern Sie nur an, was dieser Agent tut. Ein Planungsagent benötigt Schreibzugriff auf den Kalender und nichts anderes. Nicht E-Mail, nicht Kontakte, nicht Dateien. Benutzer lesen den Zustimmungsbildschirm, und eine lange Liste ist sowohl ein Vertrauensproblem als auch ein Problem der Angriffsfläche. Unser Erklärer zu OAuth 2 Scopes behandelt, wie Anbieter diese modellieren.

Fragen Sie inkrementell an. Fordern Sie das Minimum zur Verbindungszeit an und fordern Sie dann mehr an, wenn der Benutzer eine Funktion anfordert, die dies benötigt. Die an eine konkrete Anfrage gebundene Zustimmung ist einfacher zu erteilen und zu rechtfertigen.

Geben Sie jedem Agenten ein eigenes Token. Wenn ein Forschungsagent und ein Abrechnungsagent beide für denselben Benutzer agieren, leiten Sie zwei Tokens mit unterschiedlichen Scopes ab, anstatt einen zu teilen. Dann kann ein kompromittierter Forschungsagent keine Rückerstattungen vornehmen, und das Protokoll zeigt Ihnen, welcher Agent gehandelt hat.

Bevorzugen Sie standardmäßig Lese-Scopes und verlangen Sie eine explizite Eskalation für Schreibvorgänge. Kombinieren Sie dies mit einer Genehmigungsschranke bei destruktiven Aufrufen, wie in unserem Beitrag über KI-Agenten-Guardrails, damit ein Token, das schreiben kann, nicht das Einzige ist, was zwischen dem Agenten und einem Fehler steht.

Speichern, aktualisieren und widerrufen

Tokens sind Anmeldeinformationen, behandeln Sie sie also wie solche.

Speicherung. Verschlüsseln Sie Refresh-Tokens im Ruhezustand, pro Benutzer verschlüsselt. Schreiben Sie sie niemals in Protokolle, legen Sie sie niemals in Prompts ab und lassen Sie niemals ein Modell eines davon sehen. Ein Token im Kontext ist ein Token in Ihrem Trace-Speicher, den Protokollen Ihres Anbieters und möglicherweise in einer Zusammenfassung. Unser Beitrag zum Tracing von Agenten-Tool-Aufrufen behandelt das Redigieren an der Grenze und nicht zur Lesezeit.

Aktualisierung. Access-Tokens sind von Natur aus kurzlebig. Der Agent sollte dies niemals selbst verwalten; ein Token-Manager vor dem HTTP-Client aktualisiert, wenn der Ablauf nahe ist, und versucht den Aufruf einmal bei einem 401 erneut.

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

Zwei Details sind wichtig. Anbieter rotieren Refresh-Tokens zunehmend, indem sie bei jeder Aktualisierung ein neues ausstellen und das alte ungültig machen. Speichern Sie das neue daher sofort, sonst sperren Sie den Benutzer aus. Und serialisieren Sie Aktualisierungen pro Benutzer, da zwei gleichzeitige Aktualisierungen bei einem rotierenden Anbieter in einen Wettlauf geraten und einer verlieren wird.

Widerruf. Benutzer widerrufen den Zugriff, Tokens laufen ab, Administratoren entfernen Konten. Der Agent muss 401 und 403 als endgültig und nicht als wiederholbar behandeln. Das erneute Versuchen eines Authentifizierungsfehlers hilft niemals und kann Missbrauchsschutzmaßnahmen auslösen. Geben Sie eine klare Meldung mit dem Namen des Benutzers und des Scopes zurück, damit ein Mensch handeln kann, gemäß den Fehlermustern in unserem Beitrag zum API-Fehlerdesign für Agenten.

Das Zustimmungsproblem

Der schwierige Teil bei Agenten plus OAuth: Zustimmung erfordert einen Menschen, und Agenten laufen unbeaufsichtigt.

Trennen Sie Verbindungszeit von Laufzeit, und es wird handhabbar. Zur Verbindungszeit autorisiert eine Person einmalig mit einem Browser, und Sie speichern ein Refresh-Token. Zur Laufzeit verwendet der Agent diese Berechtigung ohne menschliche Beteiligung. Dies funktioniert für geplante und Hintergrundagenten, was die meisten sind.

Zwei Grenzen, die es zu beachten gilt. Grants laufen ab, manchmal nach Monaten der Nichtbenutzung, manchmal aufgrund einer Richtlinie. Erkennen Sie einen abgelaufenen Grant, beenden Sie den Lauf und benachrichtigen Sie den Benutzer, anstatt jede Nacht stillschweigend zu scheitern. Und die Zustimmung hat eine Obergrenze für den Scope: Ein Agent, der einen Scope benötigt, den der Benutzer nie gewährt hat, muss danach fragen, anstatt ihn selbst zu eskalieren.

Für alles, was von hoher Bedeutung ist, fügen Sie eine zweite Genehmigungsstufe zur Aktionszeit hinzu. Das Token beweist, dass der Agent handeln darf; eine Genehmigungsstufe entscheidet, ob er handeln sollte. Das sind unterschiedliche Fragen, und beide verdienen eine Antwort.

Testen Sie den Flow, bevor ein Agent ihn trifft

Authentifizierungscode-Pfade sind der am wenigsten getestete Teil der meisten Integrationen, da das manuelle Ausführen das Durchklicken der Bildschirme eines Anbieters bedeutet.

Erstellen Sie diese fünf Fälle:

• Glücklicher Pfad. Ein gültiger Access-Token, ein erfolgreicher Aufruf. Die Basislinie.
• Abgelaufener Access-Token. Der Anbieter gibt 401 zurück, der Manager aktualisiert, der Aufruf wird einmal wiederholt und ist erfolgreich. Dies ist der häufigste reale Pfad und oft der am wenigsten getestete.
• Widerrufener Refresh-Token. Die Aktualisierung gibt invalid_grant zurück. Der Agent muss anhalten und berichten, nicht in einer Schleife laufen.
• Ungenügender Scope. Ein 403 mit einem Scope-Fehler. Der Agent darf nicht wiederholen und muss angeben, welcher Scope fehlt.
• Gleichzeitige Aktualisierung. Zwei Aufrufe für denselben Benutzer gleichzeitig. Es sollte genau eine Aktualisierung stattfinden.

Führen Sie sie gegen Mocks aus. In Apidog können Sie den Token-Endpoint und die geschützten Endpunkte definieren und dann jede Antwort einschließlich der Fehler-Bodies simulieren, sodass die gesamte Matrix läuft, ohne einen echten Anbieter zu berühren. Unser Beitrag über das Ausführen von Agenten gegen Mocks statt Produktion behandelt die umfassendere Gewohnheit, und unser OAuth 2 API-Testleitfaden behandelt die Details auf Anfrageebene.

Drei Integrationen und was sie benötigen

Ein Kalenderassistent. Liest Verfügbarkeiten und bucht Besprechungen für einen Benutzer. Delegierter Zugriff, zwei Scopes, Zustimmung zur Verbindungszeit im Browser, danach Hintergrundausführungen. Der interessante Fehler ist der Widerruf: Der Benutzer trennt die Integration, und der nächtliche Lauf muss dies bemerken und stoppen, anstatt eine Woche lang einen toten Grant erneut zu versuchen.

Ein Support-Agent in einem gemeinsamen Posteingang. Bearbeitet Tickets, die einem Team gehören. Hier wird die Identitätsfrage schärfer. Als gemeinsames Konto des Teams zu agieren, ist vertretbar, da die Ressource tatsächlich dem Team gehört, aber jede Antwort sieht dann im Audit-Protokoll identisch aus. Besser ist eine Bot-Identität mit eigenen Scopes plus einem Protokoll, welcher Mensch den Lauf ausgelöst hat, was die Zuordnung intakt hält, ohne vorzugeben, dass der Agent eine Person ist.

Ein interner Betriebsagent. Startet Dienste neu und liest Dashboards in Ihrer eigenen Infrastruktur. Keine Benutzerdaten, keine Delegation. Ein Dienstkonto mit engen Scopes ist die richtige Antwort, und die Arbeit fließt in Rotation und Angriffsfläche statt in die Zustimmung.

Die Trennlinie ist der Besitz. Wenn die Daten jemandem gehören, der Ihren Zugriff vernünftigerweise widerrufen möchte, verwenden Sie die delegierte Authentifizierung. Wenn sie Ihnen gehören, verwenden Sie ein Dienstkonto und investieren Sie den Aufwand in die Scoping.

Den Menschen in der Zuordnung behalten

Delegierte Authentifizierung beantwortet die Frage „in wessen Auftrag“. Sie beantwortet nicht die Frage „auf wessen Anfrage“, und bei Agentenarbeit möchten Sie beides. Ein Token beweist, dass der Agent als Benutzer agieren darf; es zeichnet nicht auf, welche Person den Lauf angefordert hat.

Halten Sie diese zweite Identität neben der Arbeit. Wo Agenten zugewiesene Aufgaben ausführen, ist die Arbeitsverwaltungsebene der natürliche Ort: eine Sharkly-Aufgabe erfasst die für die Arbeit verantwortliche Person neben dem zur Ausführung zugewiesenen Agenten oder der Crew, was die menschliche Verantwortlichkeit und die Agentenausführung als zwei getrennte, sichtbare Fakten bewahrt. Die Sharkly-Dokumentation beschreibt diese Aufteilung detailliert. Unabhängig davon, wie Sie es speichern, lautet die Audit-Frage nach einem Vorfall normalerweise „Wer hat dies angefordert?“, und ein Token allein kann dies nicht beantworten.

Lassen Sie das Modell die Anmeldeinformationen nicht halten

Eine Architekturregel verhindert die meisten Authentifizierungsvorfälle in Agenten-Systemen: Das Modell sieht niemals ein Token.

Tokens werden vom Executor auf der HTTP-Ebene injiziert, nachdem das Modell ein Tool ausgewählt und Argumente erzeugt hat. Das Tool-Schema hat keinen token-Parameter, der Prompt enthält keine Anmeldeinformationen, und die Antwort, die das Modell liest, hat den Authorization-Header entfernt.

Dies ist für Agenten wichtiger als für gewöhnliche Clients, da Modell-Inputs wandern. Alles im Kontext kann in eine Übergabe zusammengefasst, in einen Trace geschrieben, in einer Fehlermeldung wiedergegeben oder an einen Benutzer zurückgegeben werden, der den Agenten gebeten hat, sich selbst zu erklären. Keiner dieser Pfade ist feindselig; es sind alles normale Funktionen, die zu Lecks werden, sobald ein Zugangsdatensatz im Scope ist. Unser Beitrag über API-Schlüssel mit geringsten Rechten für Agenten.

Dieselbe Regel gilt für die Benutzeridentität. Der Executor weiß, für welchen Benutzer dieser Lauf agiert, und wählt das Token entsprechend aus. Das Modell den Benutzer benennen zu lassen, ist eine Autorisierungsentscheidung, die von der am wenigsten vorhersehbaren Komponente im System getroffen wird.

Eine Checkliste

• Delegierter Zugriff überall dort, wo die Daten einem Benutzer gehören, Dienstkonten nur für Ihre eigenen Ressourcen.
• Autorisierungscode mit PKCE zur Verbindungszeit, Geräte-Grant für Headless-Maschinen.
• Scopes pro Agent angefordert, minimal, inkrementell eskaliert.
• Sub-Agenten erhalten ausgetauschte Tokens, keine Kopien des Benutzer-Grants.
• Refresh-Tokens im Ruhezustand verschlüsselt und niemals in Prompts, Protokollen oder Traces.
• Aktualisierung durch einen Token-Manager, pro Benutzer serialisiert, Rotation persistent gespeichert.
• 401 und 403 als endgültig behandelt, mit einer Meldung, die den Benutzer und den Scope benennt.
• Abgelaufene Grants erkannt und dem Benutzer angezeigt, nicht nächtlich erneut versucht.
• Hochriskante Aktionen durch Genehmigung zusätzlich zum Token geschützt.
• Alle fünf Authentifizierungsszenarien gegen Mocks in CI getestet.

Delegierte Authentifizierung ist mehr Arbeit als ein gemeinsamer Schlüssel, und sie verschafft Ihnen die zwei Dinge, die Sie benötigen, wenn ein Agent für andere Personen agiert: Der Benutzer kann den Zugriff widerrufen, und das Protokoll zeigt, wer was getan hat. Laden Sie Apidog herunter, um den Token-Flow und seine Fehlerfälle zu erstellen, bevor ein Agent ihn unbeaufsichtigt ausführt.

Häufig gestellte Fragen

Kann der Agent den OAuth-Zustimmungsfluss selbst abschließen? Nein, und das sollte er auch nicht versuchen. Zustimmung erfordert eine Person, die entscheidet, was gewährt werden soll. Lassen Sie einen Menschen einmalig über einen normalen Browser-Flow autorisieren und lassen Sie den Agenten dann den resultierenden Grant verwenden.

Sollte jeder Agent seinen eigenen OAuth-Client haben? Separate Clients pro Produktintegration und separate Tokens pro Agent innerhalb dessen, normalerweise über Token-Austausch. Unterschiedliche Clients helfen, wenn Anbieter pro-Client-Ratenbegrenzungen anwenden oder wenn Sie eine unabhängige Widerrufung wünschen.

Was passiert, wenn der Refresh-Token rotiert und ich den neuen verpasse? Der Benutzer wird ausgesperrt und muss sich erneut verbinden. Speichern Sie den neuen Refresh-Token in derselben Transaktion, die den alten verbraucht, und serialisieren Sie Aktualisierungen pro Benutzer, damit zwei Worker sich nicht gegenseitig überholen können.

Ist es sicher, dem Modell einen Access-Token zu zeigen? Nein. Tokens gehören in die HTTP-Schicht, injiziert von Ihrem Executor. Alles, was ein Modell sieht, kann in einem Trace, einer Zusammenfassung oder einer Antwort landen, wie in unserem Beitrag über API-Schlüssel mit geringsten Rechten für Agenten behandelt.

Wie prüfe ich, welcher Agent was getan hat? Protokollieren Sie bei jedem Aufruf die Benutzer-ID, den Agentennamen, den verwendeten Scope und den Token-Identifikator, niemals das Token selbst. Unser Beitrag zum Tracing von Agenten-Tool-Aufrufen behandelt die Struktur der Aufzeichnungen.

Was ist, wenn der Anbieter keinen Token-Austausch unterstützt? Speichern Sie separate Grants pro Agent, wo der Anbieter mehrere zulässt, oder erzwingen Sie eine Scope-Einschränkung in Ihrem eigenen Gateway, sodass die Aufrufe jedes Agenten auf seine erlaubten Operationen gefiltert werden, bevor sie Ihr Netzwerk verlassen.