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

OAuth 2.0 in API-Tests mit Apidog: Tokens verwalten und Fehlerpfade testen

Jedes API-Team stößt an die gleiche Grenze: Die Endpunkte funktionieren isoliert, bis OAuth 2.0 aktiviert wird und plötzlich die Hälfte der Testsuite 401-Fehler zurückgibt. Dann müssen Autorisierungsserver, kurzlebige Zugriffstoken und Scopes verwaltet werden – und das manuelle Kopieren eines Tokens aus einer cURL-Antwort in ein Header-Feld wird schnell zur Routinearbeit.

Apidog heute ausprobieren

Die Lösung ist nicht, Authentifizierung in Tests zu überspringen. Stattdessen sollte die Token-Verwaltung Teil des Test-Setups sein. Dieser Leitfaden zeigt die zwei wichtigsten OAuth-2.0-Flows:

• Authorization Code mit PKCE für APIs, die im Namen eines Benutzers agieren
• Client Credentials für Machine-to-Machine-Aufrufe

Eine vollständige Übersicht finden Sie in der Übersicht über OAuth 2.0 Flows.

Anschließend konfigurieren Sie OAuth 2.0 in Apidog, verwenden ein Token für mehrere Anfragen, aktualisieren abgelaufene Tokens automatisch, vererben Authentifizierung auf Ordnerebene und testen typische Fehlerpfade.

Die zwei wichtigsten OAuth-2.0-Flows

Wählen Sie den Flow anhand einer Frage:

Agiert die API im Namen eines Benutzers oder im Namen eines Dienstes?

Authorization Code Flow mit PKCE

Der Authorization Code Flow ist der Standard für benutzergebundene Tokens:

1. Der Client leitet den Benutzer zum Autorisierungsserver weiter.
2. Der Benutzer meldet sich an und stimmt zu.
3. Der Server leitet mit einem einmaligen Code zurück.
4. Der Client tauscht den Code am Token-Endpunkt gegen ein Zugriffstoken ein.

Der Ablauf ist in RFC 6749, Abschnitt 4.1 definiert.

PKCE (Proof Key for Code Exchange) schützt den Code-Austausch zusätzlich. Der Client erzeugt einen zufälligen Verifier, sendet eine daraus berechnete Challenge mit der Autorisierungsanfrage und beweist beim Einlösen des Codes, dass er den ursprünglichen Verifier besitzt. Ein abgefangener Code kann dadurch nicht allein verwendet werden.

PKCE wurde ursprünglich für mobile Apps entwickelt. Die aktuelle Empfehlung von oauth.net gilt jedoch für jeden Authorization-Code-Austausch, auch für vertrauliche Clients.

Verwenden Sie diesen Flow, wenn das Verhalten der API von der Benutzeridentität abhängt, zum Beispiel bei:

• GET /orders, das nur die Bestellungen des aktuellen Benutzers zurückgibt
• rollenbasierten Admin-Endpunkten
• benutzerbezogenen Ratenlimits

Client Credentials Flow

Der Client-Credentials-Grant kommt ohne Benutzer aus. Der Client authentifiziert sich mit seiner eigenen ID und seinem Secret und erhält ein Token, das den Dienst selbst repräsentiert:

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

Dieser Flow eignet sich für Machine-to-Machine-APIs, etwa:

• interne Microservices
• Cron-Jobs
• CI-Pipelines
• Deployment-APIs

Er ist auch für automatisierte Tests besonders praktisch, weil keine Browserinteraktion erforderlich ist. Wenn Ihre Testumgebung einen separaten Test-Client bereitstellt, verwenden Sie Client Credentials für alle Fälle, in denen nicht die Benutzeridentität getestet wird.

Weitere Details finden Sie im OAuth 2.0 Client Credentials Grant.

OAuth 2.0 in Apidog konfigurieren

Apidog behandelt OAuth 2.0 als integrierten Authentifizierungstyp. Sie konfigurieren OAuth im Auth-Tab einer Anfrage oder eines Ordners. Apidog übernimmt anschließend:

• das Abrufen des Tokens
• das Anhängen des Bearer-Tokens
• die Wiederverwendung für weitere Anfragen
• die Aktualisierung abgelaufener Tokens

Unterstützt werden unter anderem:

• Authorization Code
• Authorization Code (With PKCE)
• Client Credentials
• Password Credentials
• Implicit

Die folgenden Beispiele verwenden eine fiktive Order-Management-API.

Client Credentials einrichten

Öffnen Sie eine Anfrage oder – für mehrere Endpunkte besser – den zugehörigen Ordner. Setzen Sie den Authentifizierungstyp auf OAuth 2.0 und wählen Sie Client Credentials als Grant Type.

Tragen Sie ein:

• Access Token URL: https://auth.example.com/oauth/token
• Client ID: orders_service
• **Client [REDACTED CREDENTIAL] das bereitgestellte Secret
• Scope: orders:read orders:write Der Scope wird in den erweiterten Optionen eingestellt.

Apidog unterstützt zwei Methoden zur Übermittlung der Zugangsdaten:

1. Basic-Auth-Header
2. Request-Body

Verwenden Sie die Methode, die Ihr Autorisierungsserver erwartet. Auth0 und Okta akzeptieren in der Regel beide Varianten; manche internen Server parsen jedoch ausschließlich den Body.

Klicken Sie auf Token abrufen. Apidog ruft den Token-Endpunkt auf, speichert die Antwort und zeigt Token sowie Gültigkeitsdauer an. Beim nächsten Senden wird das Token automatisch als Bearer-Token im Authorization-Header verwendet:

[REDACTED CREDENTIAL] <access_token>

Manuelle {{token}}-Variablen sind nicht erforderlich.

Authorization Code mit PKCE einrichten

Für benutzerbezogene Tests wählen Sie Authorization Code (With PKCE). PKCE ist in Apidog ein eigener Grant Type und keine zusätzliche Checkbox.

Sie benötigen:

• Auth URL: https://auth.example.com/oauth/authorize
• Access Token URL: https://auth.example.com/oauth/token
• Callback URL: die beim Anbieter registrierte Redirect-URI
• **Client ID und Client [REDACTED CREDENTIAL] aus der OAuth-App-Registrierung

Klicken Sie auf Token abrufen. Apidog öffnet ein Browserfenster mit der Anmeldeseite. Melden Sie sich mit dem Testbenutzer an und bestätigen Sie den Zustimmungsbildschirm. Das zurückgegebene Token wird im selben verwalteten Slot gespeichert.

Gibt der Anbieter zusätzlich zum Zugriffstoken ein OpenID-Connect-ID-Token zurück, können Sie über Token Type Used festlegen, welches Token an die API angehängt wird. Das ist hilfreich, wenn die API ID-Tokens validiert.

Legen Sie für jede benötigte Rolle einen eigenen Testbenutzer an, zum Beispiel:

• Käufer
• Administrator
• Benutzer mit reinen Leserechten

So können Sie dasselbe Testszenario mit unterschiedlichen Benutzeridentitäten ausführen und rollenbasierte Zugriffsregeln schnell überprüfen.

Tokens wiederverwenden und automatisch aktualisieren

Zugriffstoken laufen typischerweise innerhalb einer Stunde ab. Ohne automatische Verwaltung führt ein abgelaufenes Token zu einem fehlerhaften Testlauf und einem manuellen erneuten Abruf.

Apidog aktualisiert OAuth-2.0-Tokens automatisch, wenn der Autorisierungsserver ein Refresh-Token ausgestellt hat. Diese Funktion wurde im Juni-Update veröffentlicht.

Wenn das gespeicherte Zugriffstoken abläuft, verwendet Apidog das Refresh-Token, ruft ein neues Zugriffstoken ab und ersetzt es vor dem Senden. Falls Ihr Anbieter eine separate URL verwendet, können Sie in den erweiterten Einstellungen eine benutzerdefinierte Refresh Token URL angeben.

Bei Client Credentials stellen viele Server kein Refresh-Token aus. Das ist zulässig, weil sich der Client jederzeit erneut authentifizieren kann. In diesem Fall genügt ein Klick auf Token abrufen. Geplante oder per CI ausgeführte Tests können zu Beginn jedes Laufs ein neues Token anfordern.

Authentifizierung auf Ordnerebene vererben

OAuth für jede einzelne Anfrage zu konfigurieren, ist die falsche Abstraktionsebene. Legen Sie die Authentifizierung stattdessen für den Ordner fest. Alle enthaltenen Anfragen erben die Konfiguration vom übergeordneten Element.

Beispiel: Konfigurieren Sie OAuth 2.0 einmal für den Ordner Orders API. Alle vorhandenen und neu hinzugefügten Anfragen verwenden anschließend dasselbe verwaltete Token.

Das ist besonders nützlich für mehrstufige Szenarien:

1. POST /carts
2. POST /carts/{id}/items
3. POST /orders

Alle Schritte teilen sich eine Authentifizierungskonfiguration. Läuft das Token während des Szenarios ab, übernimmt Apidog die Aktualisierung. Ändert sich das Client-Secret, muss nur der Ordner angepasst werden – nicht jede einzelne Anfrage.

Einzelne Anfragen können die geerbte Authentifizierung weiterhin überschreiben. Genau das benötigen Sie für negative Tests.

Fehlerpfade testen

Happy-Path-Tests zeigen, dass Ihre Token-Pipeline funktioniert. Failure-Path-Tests zeigen, dass Ihre API Authentifizierung und Autorisierung tatsächlich erzwingt. Automatisieren Sie mindestens die folgenden Fälle.

Eine Übersicht der Statuscodes finden Sie im Vergleich von API-Schlüsseln und Bearer-Tokens.

Fehlendes oder abgelaufenes [REDACTED CREDENTIAL] erwarten

Duplizieren Sie eine Anfrage und überschreiben Sie die geerbte Authentifizierung entweder mit keiner Authentifizierung oder mit einem abgelaufenen [REDACTED CREDENTIAL]
[REDACTED CREDENTIAL] expired_token_do_not_rotate

Prüfen Sie:

- Statuscode ist `401`
- der Response-Header `WWW-Authenticate` ist vorhanden
- der Response-Body enthält keine Stack-Traces oder internen Hostnamen

Ein `200` ist hier ein kritischer Sicherheitsfehler. Ein `403` deutet ebenfalls auf ein Problem hin: Der Server sollte zwischen „nicht authentifiziert“ und „authentifiziert, aber nicht berechtigt“ unterscheiden.

### Falscher Scope: 403 erwarten

Erstellen Sie einen zweiten Test-Client, der nur über `orders:read` verfügt. Rufen Sie mit dessen Token einen Schreib-Endpunkt wie `POST /orders` auf.

Erwarten Sie:

- Statuscode `403`
- bei RFC-6750-konformen APIs einen `WWW-Authenticate`-Header mit `error="insufficient_scope"`

Dieser Test entdeckt Fehlkonfigurationen, bei denen Scopes am Gateway nur für einige Routen geprüft werden. Weitere Hinweise finden Sie in [OAuth 2.0 Scopes erklärt](https://apidog.com/de/blog/what-are-oauth-2-scopes?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).

### Ungültiger Client: sauberer Fehler am Token-Endpunkt

Richten Sie eine Anfrage direkt an den Token-Endpunkt und verwenden Sie ein ungültiges `client_secret`:

http
https://auth.example.com/oauth/token

Gemäß [RFC 6749, Abschnitt 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) sollte der Server mit `400` oder – bei fehlgeschlagener Client-Authentifizierung – mit `401` antworten.

Der JSON-Body sollte enthalten:

json
{
"error": "invalid_client"
}

Prüfen Sie sowohl Statuscode als auch Fehlerobjekt. Der Autorisierungsserver ist ebenfalls eine API; sein Fehlervertrag gehört damit zu Ihrer Testabdeckung.

## Token-Antworten mit Assertions prüfen

Der Token-Endpunkt benötigt mehr Tests als nur den Fall eines ungültigen Clients. Fügen Sie ein Szenario hinzu, das den Endpunkt direkt aufruft, und prüfen Sie:

- `access_token` existiert und ist nicht leer
- `token_type` entspricht `bearer`  
  Die Groß-/Kleinschreibung wird gemäß Spezifikation ignoriert.
- `expires_in` ist größer als `0` und entspricht Ihrer Richtlinie, beispielsweise höchstens `3600`
- `scope` entspricht dem angeforderten Scope

Die letzte Assertion erkennt Server, die Berechtigungen stillschweigend einschränken.

In Apidog können Sie diese Prüfungen als visuelle Assertions auf dem Response-JSON definieren, ohne Skripte zu schreiben. Sie können `access_token` außerdem in eine Variable extrahieren, wenn Sie den vollständigen OAuth-Handshake testen möchten, statt die verwaltete Authentifizierung zu verwenden.

Verknüpfen Sie das Szenario mit Ihrem CI-Lauf. So führt ein fehlerhafter Autorisierungsserver zu einem Build-Fehler und nicht erst zu mysteriösen 401-Fehlern in der Produktion.

## Empfohlene Teststruktur

Ein vollständiger Testplan sieht so aus:

1. OAuth 2.0 auf Ordnerebene für den Happy Path konfigurieren
2. Authorization Code mit PKCE für benutzerabhängige APIs verwenden
3. Client Credentials für Dienst-zu-Dienst-Aufrufe verwenden
4. Pro-Anfrage-Overrides für fehlende, abgelaufene oder unzureichende Berechtigungen anlegen
5. Den Vertrag des Token-Endpunkts mit eigenen Assertions testen
6. Das Testszenario in CI ausführen

Apidog unterstützt den OAuth-2.0-Authentifizierungstyp auch im kostenlosen Plan. [Laden Sie Apidog herunter](https://apidog.com/download?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) und richten Sie es in wenigen Minuten auf Ihren eigenen Token-Endpunkt.

## FAQ

### Welchen OAuth-Flow sollte ich für API-Tests verwenden?

Verwenden Sie **Client Credentials** für maschinelle Aufrufe und die meisten automatisierten Testsuiten, da keine Browserinteraktion erforderlich ist.

Verwenden Sie **Authorization Code mit PKCE**, wenn der Test von der Benutzeridentität abhängt, etwa bei:

- benutzerbezogener Datenisolierung
- Rollenprüfungen
- Zustimmungsverhalten

Vermeiden Sie Implicit und Password Credentials in neuen Testplänen. Beide werden in den [aktuellen OAuth-Richtlinien](https://oauth.net/2/) nicht empfohlen.

### Wie aktualisiere ich ein abgelaufenes Token automatisch in Apidog?

Konfigurieren Sie OAuth 2.0 im Auth-Tab und klicken Sie auf **Token abrufen**. Gibt der Autorisierungsserver ein Refresh-Token zurück, aktualisiert Apidog das Access Token beim Ablauf automatisch.

Falls Ihr Anbieter eine separate Refresh-Token-URL verwendet, konfigurieren Sie diese in den erweiterten Einstellungen. Bei Client-Credentials-Setups ohne Refresh-Token rufen Sie einfach erneut ein Token ab.

### Können mehrere Anfragen in einem Szenario dasselbe OAuth-Token verwenden?

Ja. Legen Sie OAuth 2.0 für den übergeordneten Ordner fest. Die enthaltenen Anfragen erben die Konfiguration und verwenden dasselbe verwaltete Token.

Einzelne Anfragen können die Ordnerkonfiguration überschreiben. Dadurch lassen sich negative Tests mit abgelaufenen Tokens oder falschen Scopes in dasselbe Szenario integrieren.

### Was bedeutet 401 im Vergleich zu 403?

Geben Sie `401` zurück, wenn die Authentifizierung fehlgeschlagen ist – beispielsweise bei einem fehlenden, abgelaufenen oder ungültigen Token.

Geben Sie `403` zurück, wenn das Token gültig ist, aber die erforderliche Berechtigung fehlt, etwa ein bestimmter Scope.

Diese Unterscheidung beeinflusst die Wiederholungslogik von Clients: Ein `401` signalisiert, dass eine erneute Authentifizierung erforderlich ist. Ein `403` signalisiert, dass der Client die Anfrage nicht mit denselben Berechtigungen wiederholen sollte.

Weitere Informationen zur Token-Validierung finden Sie im Leitfaden zum [Testen der JWT-Authentifizierung](https://apidog.com/de/blog/test-jwt-authentication-api?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).