Wie man OAuth 2.0 APIs in Apidog testet (Autorisierungscode, Client Credentials, Token-Refresh)

Jedes API-Team stößt an die gleiche Wand. Die Endpunkte funktionieren isoliert, dann schaltet jemand OAuth 2.0 ein und die Hälfte der Testsuite gibt 401er zurück. Plötzlich jongliert man mit Autorisierungsservern, kurzlebigen Zugriffstoken und Scopes, und das manuelle Kopieren von Token aus einer Curl-Antwort in ein Header-Feld wird nach dem dritten Durchlauf langweilig.

Die Lösung besteht nicht darin, die Authentifizierung in den Tests zu überspringen. Es geht darum, die Token-Handhabung zum Teil des Test-Setups zu machen, damit sie keine manuelle Arbeit mehr ist. Dieser Leitfaden behandelt die zwei Flows, denen Sie in fast jedem Testplan begegnen werden: den OAuth-Autorisierungscode-Flow (mit PKCE) für APIs, die im Namen eines Benutzers agieren, und den Client-Credentials-Flow für Machine-to-Machine-Aufrufe. Wenn Sie zuerst die vollständige Übersicht über die Grants wünschen, geht unsere Übersicht über OAuth 2.0 Flows auf alle ein.

Danach wird es praktisch: Konfiguration der OAuth 2.0-Authentifizierung in Apidog, einmaliges Abrufen eines Tokens und dessen Wiederverwendung bei mehreren Anfragen, automatisches Aktualisieren abgelaufener Tokens, Vererbung der Authentifizierung auf Ordnerebene und Testen der Fehlerpfade, nach denen Ihre Sicherheitsprüfung fragen wird.

Die zwei Flows, die für das API-Testen wichtig sind

OAuth 2.0 definiert mehrere Grant Types, aber für das tägliche API-Testen werden Sie die meiste Zeit mit zwei davon verbringen. Wählen Sie basierend auf einer Frage aus: Agiert die API im Namen eines Benutzers oder im Namen eines Dienstes?

Autorisierungscode-Flow mit PKCE

Der Autorisierungscode-Flow ist der Standardweg, um ein an einen Benutzer gebundenes Token zu erhalten. Der Client sendet den Benutzer an den Autorisierungsserver, der Benutzer meldet sich an und stimmt zu, der Server leitet mit einem einmaligen Code zurück, und der Client tauscht den Code am Token-Endpunkt gegen ein Zugriffstoken ein. RFC 6749 definiert den gesamten Ablauf in Abschnitt 4.1.

PKCE (Proof Key for Code Exchange, RFC 7636) härtet den Austausch ab. Der Client generiert einen zufälligen Verifier, sendet eine gehashte Challenge mit der Autorisierungsanfrage und beweist dann beim Einlösen des Codes, dass er den ursprünglichen Verifier besitzt. Ein Angreifer, der den Code abfängt, kann ihn nicht verwenden. PKCE begann als Fehlerbehebung für mobile Apps, aber die aktuelle Empfehlung von oauth.net empfiehlt es für jeden Autorisierungscode-Austausch, einschließlich vertraulicher Clients.

Testen Sie mit diesem Flow immer dann, wenn das Verhalten des Endpunkts davon abhängt, wer der Benutzer ist: GET /orders, das nur die Bestellungen des Anrufers zurückgibt, rollenbasierte Admin-Endpunkte, Ratenbegrenzungen pro Benutzer.

Client Credentials Flow

Der OAuth 2.0 Client Credentials Grant überspringt den Benutzer vollständig. Der Client authentifiziert sich mit seiner eigenen ID und seinem Secret und erhält ein Token, das die Anwendung selbst repräsentiert. Ein POST an den Token-Endpunkt, kein Browser, keine Weiterleitung:

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=orders_service \
  -d client_secret=s3cr3t_value \
  -d scope="orders:read orders:write"

Dies ist der Flow für Machine-to-Machine-APIs: interne Microservices, Cron-Jobs, CI-Pipelines, die eine Deployment-API aufrufen. Es ist auch das Arbeitstier des automatisierten Testens, da kein Mensch involviert sein muss. Wenn Ihre Testumgebung es Ihnen ermöglicht, einen Test-Client bereitzustellen, verwenden Sie Client Credentials für alles außer den Fällen, in denen die Benutzeridentität das zu testende Element ist.

OAuth 2.0 Auth in Apidog konfigurieren

Apidog behandelt OAuth 2.0 als erstklassigen Authentifizierungstyp. Sie konfigurieren es einmal, im Auth-Tab einer Anfrage oder eines Ordners, und die Plattform kümmert sich um das Abrufen, Anhängen und Aktualisieren von Tokens. Unterstützte Grant Types umfassen Authorization Code, Authorization Code (With PKCE), Client Credentials, Password Credentials und Implicit.

Hier ist das Setup für die beiden oben genannten Flows, unter Verwendung einer fiktiven Order-Management-API.

Client Credentials Setup

Öffnen Sie die Anfrage (oder besser, den Ordner; mehr dazu unten), ändern Sie den Auth-Typ auf OAuth 2.0 und wählen Sie Client Credentials als Grant Type. Füllen Sie Folgendes aus:

• Access Token URL: https://auth.example.com/oauth/token
• Client ID: orders_service
• Client Secret: Ihr bereitgestelltes Secret
• Scope: orders:read orders:write (unter den erweiterten Optionen einzustellen)

Apidog bietet Ihnen zwei Möglichkeiten, die Anmeldeinformationen zu übermitteln: als Basic Auth Header oder im Anfragetext. Passen Sie an, was Ihr Autorisierungsserver erwartet; Auth0 und Okta akzeptieren beides, aber einige interne Server parsen nur den Body.

Klicken Sie auf Token abrufen. Apidog ruft den Token-Endpunkt auf, speichert das Ergebnis und zeigt das Token zusammen mit seiner Gültigkeitsdauer an. Von da an hängt jeder Sendevorgang es an den Authorization-Header mit dem Bearer-Präfix an. Kein Kopieren und Einfügen, keine {{token}}-Variablenverdrahtung.

Autorisierungscode-Setup mit PKCE

Für Tests im Benutzerkontext wählen Sie „Authorization Code (With PKCE)“ als Grant-Typ. PKCE ist in Apidog eine eigene Grant-Option, keine Checkbox. Sie benötigen einige weitere Felder:

• Auth URL: https://auth.example.com/oauth/authorize
• Access Token URL: https://auth.example.com/oauth/token
• Callback URL: die bei Ihrem Anbieter registrierte Weiterleitungs-URI
• Client ID und Client Secret: aus Ihrer OAuth-App-Registrierung

Klicken Sie auf Token abrufen und Apidog öffnet ein Browserfenster, das auf die Anmeldeseite verweist. Melden Sie sich als Ihr Testbenutzer an, stimmen Sie dem Zustimmungsbildschirm zu, und das Token kommt zurück und landet im selben verwalteten Slot wie zuvor. Wenn Ihr Anbieter neben dem Zugriffstoken ein OpenID Connect ID-Token zurückgibt, können Sie mit der Option „Token Type Used“ festlegen, welches davon angehängt wird; nützlich, wenn die zu testende API ID-Token validiert.

Ein praktischer Tipp: Halten Sie für jede Rolle, die Sie abdecken müssen (Käufer, Administrator, reiner Prüfer), einen dedizierten Testbenutzer bereit. Das Abrufen eines Tokens als jeder Benutzer und das erneute Ausführen desselben Szenarios ist der schnellste Weg, um rollenbasierte Zugriffsregeln zu überprüfen.

Token-Wiederverwendung und automatische Aktualisierung

Zugriffstoken laufen ab, normalerweise innerhalb einer Stunde. Bevor Apidog dies handhabte, bedeutete ein abgelaufenes Token einen fehlgeschlagenen Durchlauf und ein manuelles erneutes Abrufen, was genau die Art von fehlerhaften Fehlern ist, die Teams ignorieren lernen.

Jetzt aktualisiert Apidog OAuth 2.0-Token selbstständig, wenn der Autorisierungsserver ein Refresh Token ausgegeben hat, eine Funktion, die im Juni-Update ausgeliefert wurde. Wenn das gespeicherte Zugriffstoken abläuft, verwendet Apidog das Refresh Token, um ein neues zu erhalten und tauscht es vor dem Senden aus. Sie können in den erweiterten Einstellungen auch auf eine benutzerdefinierte Refresh Token URL verweisen, wenn Ihr Anbieter die beiden Endpunkte trennt.

Für Client Credentials überspringen viele Server Refresh Tokens vollständig (die Spezifikation erlaubt es, da der Client sich jederzeit neu authentifizieren kann). In der Praxis ist dies unschädlich: Ein erneutes Abrufen mit Token abrufen ist ein Klick, und geplante oder CI-Läufe können zu Beginn jedes Laufs ein frisches Token anfordern.

Authentifizierung auf Ordnerebene erben

Die Konfiguration von OAuth für jede Anfrage ist die falsche Flughöhe. Apidog ermöglicht es Ihnen, die Authentifizierung für einen Ordner festzulegen, und Anfragen innerhalb dieses Ordners erben die Konfiguration von ihrem übergeordneten Element. Legen Sie OAuth 2.0 einmal für Ihren Ordner „Orders API“ fest, und jede Anfrage darunter, einschließlich neuer, die Ihre Teamkollegen im nächsten Sprint hinzufügen, sendet dasselbe verwaltete Token.

Dies ist besonders wichtig in mehrstufigen Testszenarien. Ein Checkout-Szenario könnte POST /carts, POST /carts/{id}/items und POST /orders verketten. Mit ordnerbasierter Authentifizierung teilen sich alle drei Schritte ein Token und eine Konfiguration. Wenn das Token mitten im Szenario abläuft, deckt die automatische Aktualisierung dies ab. Und wenn Ihr Sicherheitsteam das Client-Secret ändert, aktualisieren Sie einen Ordner anstelle von vierzig Anfragen.

Anfragen behalten die Option, das übergeordnete Element zu überschreiben, was genau das ist, was Sie für negative Tests wünschen. Mehr dazu jetzt.

Testen der Fehlerpfade

Happy-Path-OAuth-Tests beweisen, dass Ihre Token-Pipeline funktioniert. Failure-Path-Tests beweisen, dass Ihre API die Authentifizierung erzwingt. Überspringen Sie sie, und Sie vertrauen den Standardeinstellungen des Frameworks. Hier sind die drei Fälle, die es sich lohnt zu automatisieren; eine Auffrischung, was jeder Statuscode bedeuten sollte, finden Sie in unserem Vergleich von API-Schlüsseln und Bearer-Tokens.

Abgelaufenes oder fehlendes Token: Erwarte 401

Duplizieren Sie eine Anfrage in Ihrem Szenario und überschreiben Sie die geerbte Authentifizierung entweder mit keiner Authentifizierung oder mit einem hartkodierten, längst abgelaufenen Bearer-Token wie Bearer expired_token_do_not_rotate. Prüfen Sie Folgendes:

• Statuscode ist 401
• Der WWW-Authenticate-Antwortheader ist vorhanden (RFC 6749's Begleitdokument, RFC 6750, erwartet ihn)
• Der Body leckt keine Stack-Traces oder internen Hostnamen

Ein 200 hier ist ein kritischer Fehler. Ein 403 ist ein Design-Fehler, der ein Ticket wert ist: Der Server sollte zwischen „Ich weiß nicht, wer du bist“ und „Ich kenne dich, und nein“ unterscheiden.

Falscher Scope: erwarte 403

Stellen Sie einen zweiten Test-Client bereit, der auf orders:read beschränkt ist, rufen Sie dessen Token ab und rufen Sie einen Schreib-Endpunkt wie POST /orders auf. Überprüfen Sie, ob der Status 403 ist und, falls Ihre API RFC 6750 folgt, der WWW-Authenticate-Header error="insufficient_scope" enthält. Dieser Test fängt die klassische Fehlkonfiguration ab, bei der Scopes am Gateway für einige Routen überprüft und bei anderen vergessen werden. Wenn Scopes für Ihr Team neu sind, erklärt OAuth 2.0 Scopes erklärt, wie man sie aufteilt.

Ungültiger Client: erwarte einen sauberen Token-Endpunkt-Fehler

Richten Sie eine Anfrage direkt an https://auth.example.com/oauth/token mit einem ungültigen client_secret. Gemäß RFC 6749 Abschnitt 5.2 sollte der Server 400 (oder 401 für fehlgeschlagene Client-Authentifizierung) mit einem JSON-Body zurückgeben, der "error": "invalid_client" enthält. Überprüfen Sie beides. Autorisierungsserver sind ebenfalls APIs, und ihr Fehlervertrag ist Teil Ihrer Oberfläche.

Assertions zu Token-Antworten in Testszenarien

Der Token-Endpunkt verdient eine eigene Abdeckung, die über den Fall des ungültigen Clients hinausgeht. Fügen Sie in Ihrem Testszenario einen Schritt hinzu, der den Token-Endpunkt direkt aufruft, und fügen Sie dann Assertions zur Antwort hinzu:

• access_token existiert und ist nicht leer
• token_type ist gleich bearer (Groß-/Kleinschreibung wird gemäß Spezifikation ignoriert)
• expires_in ist größer als 0 und innerhalb Ihrer Richtlinie, z. B. nicht mehr als 3600
• scope stimmt mit dem angeforderten überein, um Server zu erkennen, die Berechtigungen stillschweigend einschränken

Die Testszenarien von Apidog ermöglichen es Ihnen, diese als visuelle Assertions auf dem Antwort-JSON hinzuzufügen, ohne dass Skripte erforderlich sind, und Sie können access_token in eine Variable für einen Folgeschritt extrahieren, wenn Sie den rohen Handshake testen möchten, anstatt die verwaltete Authentifizierung zu verwenden. Verknüpfen Sie das Szenario mit Ihrem CI-Lauf, und ein falsch funktionierender Autorisierungsserver führt zum Build-Fehler, anstatt als mysteriöser 401er in der Produktion aufzutauchen.

Der gesamte Ablauf sieht so aus: OAuth 2.0-Konfiguration auf Ordnerebene für den Happy Path, pro-Anfrage-Overrides für die 401- und 403-Fälle und ein Szenario, das den Vertrag des Token-Endpunkts testet. Das deckt benutzerkontextabhängige APIs über Autorisierungscode mit PKCE und Dienst-zu-Dienst-APIs über Client Credentials ab, wobei die Token-Aktualisierung für Sie übernommen wird. Laden Sie Apidog herunter und probieren Sie es kostenlos aus; der OAuth 2.0-Authentifizierungstyp funktioniert im kostenlosen Plan, so dass Sie ihn innerhalb weniger Minuten auf Ihren eigenen Token-Endpunkt richten können.

FAQ

Welchen OAuth-Flow sollte ich für das API-Testen verwenden?

Verwenden Sie Client Credentials für alles, was maschinell abläuft, und für die meisten automatisierten Suiten, da keine Browserinteraktion erforderlich ist. Verwenden Sie den Autorisierungscode-Flow mit PKCE, wenn der Test von der Benutzeridentität abhängt: benutzerbezogene Datenisolierung, Rollenprüfungen oder Zustimmungsverhalten. Vermeiden Sie die impliziten und Passwort-Grants in neuen Testplänen; beide werden in den aktuellen OAuth-Richtlinien nicht empfohlen.

Wie aktualisiere ich ein abgelaufenes Token automatisch in Apidog?

Konfigurieren Sie OAuth 2.0 im Auth-Tab und rufen Sie ein Token mit "Token abrufen" ab. Wenn der Autorisierungsserver ein Refresh Token zurückgibt, aktualisiert Apidog das Access Token beim Ablauf, ohne dass Sie sich neu authentifizieren müssen, und Sie können eine separate Refresh Token URL in den erweiterten Einstellungen festlegen, wenn Ihr Anbieter eine solche verwendet. Bei Client Credentials-Setups ohne Refresh Tokens führt das erneute Ausführen von "Token abrufen" zu einem neuen Token.

Kann jede Anfrage in einem Szenario ein einziges OAuth-Token teilen?

Ja. Legen Sie die OAuth 2.0-Konfiguration für den übergeordneten Ordner fest, und die darin enthaltenen Anfragen erben diese, sodass ein mehrstufiges Szenario unter einem einzigen verwalteten Token abläuft. Einzelne Anfragen können die Ordnerkonfiguration weiterhin überschreiben, wodurch Sie negative Tests (abgelaufenes Token, falscher Scope) in dasselbe Szenario einfügen können.

Was sollte ein 401 im Vergleich zu einem 403 in OAuth-geschützten APIs bedeuten?

Geben Sie 401 zurück, wenn die Authentifizierung fehlgeschlagen ist: Das Token fehlt, ist abgelaufen oder fehlerhaft. Geben Sie 403 zurück, wenn das Token gültig ist, aber die Berechtigung fehlt, z. B. ein fehlender Scope. Das Verwechseln bricht die Wiederholungslogik des Clients, da ein 401 dem Client sagt, er solle sich neu authentifizieren, während ein 403 ihm sagt, er solle aufhören. Unser Leitfaden zum Testen der JWT-Authentifizierung befasst sich mit der Validierung des Tokens selbst.