Viele APIs erfordern, dass der Client Anmeldedaten bereitstellt, die die Identität verifizieren und Zugriff gewähren. Zu den gängigen Ansätzen gehören HTTP-Authentifizierungsschemas, die in Headern gesendet werden (Basic, NTLM oder Digest), Token-basierter Zugriff (wie OAuth 2.0, bei dem ein Access-Token abgerufen und dann üblicherweise in einem Authorization-Header gesendet wird), gegenseitiges TLS mit einem Client-Zertifikat oder eine Kombination dieser Methoden.
Dieser Artikel behandelt die HTTP-Header- und Token-basierten Authentifizierungsoptionen bei Uptrends. Zur Authentifizierung mit Client-Zertifikaten siehe Client-Zertifikats-Authentifizierung.
Standard-Authentifizierungsarten
Der Abschnitt Authentifizierung auf der Registerkarte Request bietet mehrere Möglichkeiten zum Senden von Anmeldedaten:
- Basic Authentication
- NTLM (Windows) Authentifizierung
- Digest Authentication
- Bearer-Authentifizierung
- Keine — wähle diese Option, wenn der Schritt keine Authentifizierung erfordert.
Basic Authentication
Verwendet einen Benutzernamen und ein Passwort für die Authentifizierung. Uptrends erzeugt den Authorization-Header automatisch. Du musst diesen Header nicht manuell hinzufügen.
Uptrends ruft die API möglicherweise zuerst auf, ohne deinen Benutzernamen und dein Passwort zu senden. Wenn eine Authentifizierung erforderlich ist, verweigert der Server den Zugriff und fordert Basic Authentication an. Dieses Szenario wird als Challenge bezeichnet: Der Server antwortet mit 401 Unauthorized und einem WWW-Authenticate: Basic-Header.
Uptrends wiederholt dann den API-Aufruf mit deinem Benutzernamen und deinem Passwort. Es kombiniert deine Anmeldedaten als username:password, codiert das Ergebnis mit Base64 und sendet es im Authorization-Header. Selbst wenn Uptrends mehrere API-Aufrufe durchführt, zählt dies weiterhin als ein Prüfobjektschritt.
Notiz
Wenn der Server
403 Forbiddenzurückgibt oder einWWW-Authenticate: Basic-Header fehlt, gibt das Prüfobjekt einen Fehler zurück. Füge den HeaderAuthorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=manuell zum Prüfobjektschritt hinzu, damit die Anmeldedaten auch ohne eine korrekte Challenge mitgesendet werden. Informationen zum Header-Format findest du im Basic Authentication-Schema (RFC 7617).
NTLM (Windows) Authentifizierung
Verwendet einen Windows- oder Active Directory-Benutzernamen und ein Passwort für die Authentifizierung. Uptrends erzeugt den Authorization-Header automatisch. Du musst diesen Header nicht manuell hinzufügen.
Uptrends ruft die API möglicherweise zuerst auf, ohne deine Anmeldedaten zu senden. Wenn eine Authentifizierung erforderlich ist, verweigert der Server den Zugriff und fordert NTLM-Authentifizierung an. Dieses Szenario wird als Challenge bezeichnet: Der Server antwortet mit 401 Unauthorized und einem WWW-Authenticate: NTLM-Header.
Uptrends sendet dann möglicherweise mehrere HTTP-Anfragen, um deine Identität zu verifizieren, bevor der API-Aufruf erfolgreich ist. Selbst wenn Uptrends mehrere API-Aufrufe durchführt, zählt dies weiterhin als ein Prüfobjektschritt.
Notiz
Wenn der Server
403 Forbiddenzurückgibt oder einWWW-Authenticate: NTLM-Header fehlt, gibt das Prüfobjekt einen Fehler zurück. Anders als bei Basic Authentication gibt es keine einfache manuelle Header-Alternative. Wenn dein Konto zu einer Windows-Domain gehört, gib den Benutzernamen alsYOURDOMAIN\usernameein (zum BeispielACME\john).
Digest Authentication
Verwendet einen Benutzernamen und ein Passwort für die Authentifizierung. Uptrends erzeugt den Authorization-Header automatisch. Du musst diesen Header nicht manuell hinzufügen.
Uptrends ruft die API möglicherweise zuerst auf, ohne deine Anmeldedaten zu senden. Wenn eine Authentifizierung erforderlich ist, verweigert der Server den Zugriff und fordert Digest Authentication an. Dieses Szenario wird als Challenge bezeichnet: Der Server antwortet mit 401 Unauthorized und einem WWW-Authenticate: Digest-Header.
Uptrends wiederholt dann den API-Aufruf. Es berechnet eine MD5-basierte Antwort aus Benutzername, Passwort, Server-Challenge, Anfragemethode und URL und sendet sie im Authorization-Header. Das Passwort selbst wird nie gesendet. Selbst wenn Uptrends mehrere API-Aufrufe durchführt, zählt dies weiterhin als ein Prüfobjektschritt.
Notiz
Wenn der Server
403 Forbiddenzurückgibt oder einWWW-Authenticate: Digest-Header fehlt, gibt das Prüfobjekt einen Fehler zurück. Anders als bei Basic Authentication gibt es keine einfache manuelle Header-Alternative.
Bearer-Authentifizierung
Verwendet ein Bearer-Token anstelle eines Benutzernamens und Passworts. Uptrends fügt Authorization: Bearer <token> automatisch zur API-Anfrage dieses Schritts hinzu. Du musst diesen Header nicht manuell hinzufügen. Anders als bei anderen Authentifizierungsarten ist keine Server-Challenge erforderlich.
Notiz
Verwende Bearer-Authentifizierung, wenn du bereits ein Token hast. Verwende benutzerdefinierte Authentifizierung (OAuth), wenn du zuerst ein Token abrufen musst oder wenn das Token aus der Antwort eines vorherigen Schritts stammt.
Variablen-Support
Die Felder für Benutzername und Passwort unterstützen Variablen. Du kannst vordefinierte Variablen (zum Beispiel: {{username}} und {{password}}) mit den entsprechenden Werten erstellen und diese Variablennamen dann in den Authentifizierungsfeldern verwenden.
Du kannst für Anmeldedaten auch Vault Items verwenden.
Anweisungen zur Verwendung vordefinierter Variablen findest du unter Multi-step API-Variablen.
Benutzerdefinierte Authentifizierung (einschließlich OAuth)
Notiz
Verwende Bearer-Authentifizierung, wenn du bereits ein Token hast. Verwende benutzerdefinierte Authentifizierung (OAuth), wenn du zuerst ein Token abrufen musst oder ein Token aus der Antwort eines vorherigen Schritts stammt.
Wenn deine API OAuth als Authentifizierungsprotokoll nutzt, benötigst du ein ausgefeilteres Setup. Abhängig von deiner API benötigst du möglicherweise etwas Spezielles für deine Situation. OAuth 2.0 nutzt insbesondere mindestens eine separate Anfrage nur für den Authentifizierungsprozess. Diese Anfrage fordert Zugriff auf die API an (unter Verwendung einer der Standard-Authentifizierungsarten, durch Angabe von Anmeldedaten in der URL oder sogar durch Ausführen einer Webseitenanmeldung). Nach erfolgreicher Authentifizierung wird das OAuth-Access-Token erfasst und in einer Variablen gespeichert, sodass es in nachfolgenden Anfragen verwendet werden kann.
Wenn du nicht OAuth, sondern ein anderes Protokoll verwendest, kann es dennoch auf ähnliche Weise funktionieren: Du musst zunächst Anmeldeinformationen angeben, die deine Identität gegenüber der API “beweisen”. Der API-Server antwortet dann, indem er dir ein Anmelde-Token gibt, das für eine bestimmte Dauer gültig ist. Durch Erfassen dieses Tokens und Speichern in einer Variablen kannst du eine Reihe von Anfragen ausführen, die das Anmelde-Token verwenden, um Zugriff zu erhalten.
OAuth 2.0-Authentifizierung einrichten
Im folgenden Beispiel richten wir eine einfache Form der OAuth 2.0-Authentifizierung ein. Unser Ziel ist es, ein Access-Token von der API zu erhalten, das wir dann in späteren Anfragen verwenden können.
Dazu senden wir zunächst eine Anfrage, die die entsprechenden OAuth-Felder enthält. In diesem Fall fordern wir Zugriff auf Basis eines Autorisierungscodes, einer Client-ID und eines Client-Geheimnisses an. Die Client-ID und das Client-Geheimnis sind feste Werte, die wir als vordefinierte Variablen definieren können. In unserem einfachen Setup ist auch der Autorisierungscode ein fester Wert, aber in deinem Setup kann es notwendig sein, diesen Autorisierungscode zuerst mit einem separaten Schritt abzurufen.
Zuerst fügen wir diese Werte zu den vordefinierten Variablen hinzu:
Wenn diese Variablen definiert sind, können wir nun eine Anfrage an unsere API einrichten, indem wir Verweise auf diese Variablen zusammen mit allen anderen Parametern aufnehmen, die die API erwartet. Füge im ersten Schritt unseres Multi-step-Setups diese URL hinzu:
GET https://myapi.com/oauth/token?grant_type=authorization_code&code={{authorizationcode}}&client_id={{clientid}}&client_secret={{clientsecret}}
Wir erwarten, dass die API eine Datenstruktur zurückgibt, die das benötigte Access-Token enthält, aber wie wird diese Datenstruktur formatiert sein? Um sicherzustellen, dass wir JSON-formatierte Daten erhalten, teilen wir dem Server mit, dass wir nur das Format application/json akzeptieren, indem wir dies in einem HTTP-Header angeben:
Wenn dieser Header angegeben ist, können wir nun erwarten, dass die Antwort ungefähr so aussieht:
{ "access_token":"SGV5ISBZb3UgZm91bmQgdGhpcyB0ZXh0IQ==", "token_type":"Bearer", "expires_in":86400 }
Jetzt müssen wir nur noch das Feld access_token in der JSON-Antwort erfassen. Dazu erstellen wir eine neue Variable auf der Registerkarte Response unseres Schritts:
- Die Antwort sollte JSON enthalten, wähle daher
Response body as JSONals Quelle für unsere Variable. - Da sich das Attribut
access_tokenauf oberster Ebene in unserer Datenstruktur befindet, lautet unser JSON-Ausdruck einfachaccess_token. - Wir wählen
accesstokenals Variablennamen. Auf diesen Namen beziehen wir uns in späteren Schritten.
Obwohl das Hauptziel dieses ersten Schritts darin besteht, das Access-Token zu erfassen, führt er bereits auch ein Monitoring aus: Wenn die API an dieser Stelle einen Fehler zurückgibt oder wenn die Antwort kein Access-Token enthält, erkennt dieser Schritt dies und meldet einen Fehler.
Da wir nun ein gültiges Access-Token haben, können wir endlich auf die eigentliche API-Methode zugreifen, die wir prüfen möchten (zum Beispiel zum Abrufen einer Liste von Produkten). Erstelle einen neuen Schritt, um diesen API-Aufruf zu definieren. Nachdem wir die Methode und URL für diese neue Anfrage angegeben haben, geben wir das Access-Token weiter, das wir gerade erfasst haben. Auf OAuth 2.0 basierende APIs erwarten einen HTTP-Header namens Authorization mit dem Wert Bearer {{accesstoken}}
Wir können dies für jeden zusätzlichen Schritt wiederholen, der dasselbe Access-Token benötigt.