Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen
Lerninhalte
In dieser Anleitung lernen Sie Folgendes:
- Erstellen Sie einen API-Proxy, der einen API-Schlüssel erfordert.
- Ein API-Produkt hinzufügen
- Fügen Sie einen Entwickler hinzu und registrieren Sie eine App.
- API mit einem API-Schlüssel aufrufen
Es ist wichtig, Ihre API vor nicht autorisiertem Zugriff zu schützen. Eine Möglichkeit dafür sind API-Schlüssel (auch als öffentliche Schlüssel, Nutzerschlüssel oder Anwendungsschlüssel bezeichnet).
Wenn eine Anwendung eine Anfrage an Ihre API sendet, muss sie einen gültigen Schlüssel angeben. Während der Laufzeit prüft die Richtlinie zum Prüfen des API-Schlüssels, ob der bereitgestellte API-Schlüssel:
- Ist gültig
- Wurde nicht widerrufen
- Stimmt mit dem API-Schlüssel für das API-Produkt überein, das die angeforderten Ressourcen verfügbar macht
Wenn der Schlüssel gültig ist, ist die Anfrage zulässig. Wenn der Schlüssel ungültig ist, führt die Anfrage zu einem Autorisierungsfehler.
In dieser Anleitung erstellen Sie einen API-Proxy, für den ein gültiger API-Schlüssel erforderlich ist.
Voraussetzungen
- Ein Apigee Edge-Konto. Wenn Sie noch kein Konto haben, können Sie sich entsprechend der Anleitung unter Apigee Edge-Konto erstellen registrieren.
- Ein Webbrowser, der einen API-Aufruf durchführt.
- (Für den Abschnitt zu zusätzlichen Gutschriften ist nicht erforderlich) cURL muss auf Ihrem Computer installiert sein, um API-Aufrufe über die Befehlszeile auszuführen.
API-Proxy erstellen
- Rufen Sie https://apigee.com/edge auf und melden Sie sich an.
Wechseln Sie zu der gewünschten Organisation. Klicken Sie dazu oben in der seitlichen Navigationsleiste auf Ihren Nutzernamen, um das Nutzerprofilmenü aufzurufen, und wählen Sie die Organisation aus der Liste aus.
-
Klicken Sie auf der Landingpage auf API-Proxys, um die Liste der API-Proxys aufzurufen.
- Klicken Sie auf + Proxy.
- Wählen Sie auf der Seite Proxy erstellen die Option Reverse-Proxy (am gängigsten) aus.
- Konfigurieren Sie den Proxy auf der Seite Proxy-Details wie folgt:
In diesem Feld tun Sie Folgendes Proxy-Name Eingeben: helloworld_apikey
Projektbasispfad Ändern zu:
/helloapikey
Der Projektbasispfad ist Teil der URL, die für Anfragen an den API-Proxy verwendet wird.
Hinweis: Empfehlungen von Apigee zur API-Versionsverwaltung finden Sie unter Versionsverwaltung im E-Book Web API Design: The Missing Link.
Vorhandene API Eingeben:
http://mocktarget.apigee.net
Dies definiert die Ziel-URL, die Apigee Edge bei einer Anfrage an den API-Proxy aufruft.
Beschreibung Eingeben: hello world protected by API key
- Klicken Sie auf Weiter.
- Wählen Sie auf der Seite Allgemeine Richtlinien unter Sicherheit: Autorisierung die Option API-Schlüssel aus und klicken Sie dann auf Weiter. Dadurch werden Ihrem API-Proxy zwei Richtlinien hinzugefügt.
- Wählen Sie auf der Seite Virtuelle Hosts default und secure aus und klicken Sie dann auf Weiter. Wenn Sie Standard auswählen, können Sie Ihre API mit
http://
aufrufen. Wenn Sie sicher auswählen, können Sie Ihre API mithttps://
aufrufen. - Achten Sie darauf, dass auf der Seite Zusammenfassung die Bereitstellungsumgebung test ausgewählt ist, und klicken Sie dann auf Erstellen und bereitstellen.
- Sie erhalten eine Bestätigung, dass der neue API-Proxy und ein API-Produkt erfolgreich erstellt und der API-Proxy in Ihrer Testumgebung bereitgestellt wurde.
- Klicken Sie auf Proxy bearbeiten, um die Seite Übersicht für den API-Proxy aufzurufen.
Richtlinien ansehen
- Klicken Sie im API-Proxy-Editor auf den Tab Develop. Sie sehen, dass zwei Richtlinien dem Anfrageablauf des API-Proxys hinzugefügt wurden:
- API-Schlüssel prüfen:Prüft, ob im API-Aufruf ein gültiger API-Schlüssel vorhanden ist (wird als Abfrageparameter gesendet).
- Remove Query Param apikey:EineAssignMessage-Richtlinie, mit der der API-Schlüssel nach der Prüfung entfernt wird, damit er nicht weitergegeben und unnötigerweise verfügbar gemacht wird.
-
Klicken Sie in der Ablaufansicht auf das Symbol für die Richtlinie „API-Schlüssel prüfen“ und sehen Sie sich in der unteren Codeansicht die XML-Konfiguration der Richtlinie an. Mit dem Element
<APIKey>
wird der Richtlinie mitgeteilt, wo beim Aufruf nach dem API-Schlüssel gesucht werden soll. Standardmäßig wird in der HTTP-Anfrage nach dem Schlüssel als Abfrageparameterapikey
gesucht:<APIKey ref="request.queryparam.apikey" />
Der Name
apikey
ist beliebig und kann ein beliebiges Attribut sein, das den API-Schlüssel enthält.
Versuchen Sie, die API aufzurufen
In diesem Schritt führen Sie einen erfolgreichen API-Aufruf direkt an den Zieldienst aus. Anschließend führen Sie einen erfolglosen Aufruf an den API-Proxy aus, um zu sehen, wie er durch die Richtlinien geschützt ist.
-
Erfolg
Rufen Sie in einem Webbrowser die folgende Adresse auf. Dies ist der Zieldienst, an den der API-Proxy die Anfrage weiterleitet, aber Sie führen ihn vorerst direkt an:
http://mocktarget.apigee.net
Sie sollten folgende erfolgreiche Antwort erhalten:
Hello, Guest!
. -
Fehler
Versuchen Sie nun, den API-Proxy aufzurufen:
http://ORG_NAME-test.apigee.net/helloapikey
Ersetzen Sie
ORG_NAME
durch den Namen Ihrer Edge-Organisation.Ohne die Richtlinie „API-Schlüssel verifizieren“ würde dieser Aufruf die gleiche Antwort wie der vorherige Aufruf zurückgeben. In diesem Fall sollten Sie jedoch die folgende Fehlerantwort erhalten:
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
Das bedeutet, dass Sie keinen gültigen API-Schlüssel (als Abfrageparameter) übergeben haben.
Als Nächstes fügen Sie ein API-Produkt hinzu.
API-Produkt hinzufügen
So fügen Sie ein API-Produkt über die Apigee-Benutzeroberfläche hinzu:
- Wählen Sie Publish > API Products aus.
- Klicken Sie auf +API Product.
Geben Sie die Produktdetails für Ihr API-Produkt ein.
Feld Beschreibung Name Interner Name des API-Produkts. Der Name darf keine Sonderzeichen enthalten.
Hinweis:Sie können den Namen nicht mehr bearbeiten, nachdem das API-Produkt erstellt wurde. Beispiel:helloworld_apikey-Product
.Anzeigename Anzeigename für das API-Produkt. Der Anzeigename wird in der UI verwendet und kann jederzeit bearbeitet werden. Wenn keine Angabe erfolgt, wird der Wert für Name verwendet. Dieses Feld wird automatisch mit dem Wert „Name“ ausgefüllt. Sie können dessen Inhalt bearbeiten oder löschen. Der Anzeigename kann Sonderzeichen enthalten. Beispiel: helloworld_apikey-Product
.Beschreibung Beschreibung des API-Produkts. Beispiel: Test product for tutorial
.Umgebung Umgebungen, auf die das API-Produkt Zugriff gewährt. Beispiel: test
oderprod
.Zugriff Wählen Sie Public aus. Zugriffsanfragen automatisch genehmigen Aktivieren Sie die automatische Genehmigung von Schlüsselanfragen für dieses API-Produkt von jeder App aus. Kontingent Für diese Anleitung ignorieren. Erlaubte OAuth-Bereiche Für diese Anleitung ignorieren. - Wählen Sie im Abschnitt „API-Ressourcen“ den gerade erstellten API-Proxy aus. Beispiel:
helloworld_apikey
. - Klicken Sie auf Hinzufügen.
- Fügen Sie im Abschnitt Pfade den Pfad „/“ hinzu.
- Klicken Sie auf Hinzufügen.
- Klicken Sie auf Speichern.
In den nächsten Schritten erhalten Sie den erforderlichen API-Schlüssel.
Ihrer Organisation einen Entwickler und eine App hinzufügen
Als Nächstes simulieren wir den Workflow eines Entwicklers, der sich für die Verwendung Ihrer APIs anmeldet. Ein Entwickler hat eine oder mehrere Apps, die Ihre APIs aufrufen, und jede App erhält einen eindeutigen API-Schlüssel. Dadurch erhalten Sie als API-Anbieter eine detailliertere Kontrolle über den Zugriff auf Ihre APIs und detailliertere Berichte über den API-Traffic nach Anwendung.
Entwickler erstellen
So erstellen Sie einen Entwickler:
- Wählen Sie im Menü Veröffentlichen > Entwickler aus.
- Klicken Sie auf + Entwickler.
Geben Sie im Fenster "New Developer" Folgendes ein:
In diesem Feld eingeben Vorname Keyser
Nachname Soze
Nutzername keyser
E-Mail keyser@example.com
- Klicken Sie auf Erstellen.
App registrieren
So registrieren Sie eine Entwickler-App:
- Wählen Sie Veröffentlichen > Apps aus.
- Klicken Sie auf + App.
Geben Sie im Fenster New App (Neue App) Folgendes ein:
pIn diesem Feld tun Sie Folgendes Name und Anzeigename Eingeben: keyser_app
Unternehmen / Entwickler Wählen Sie Developer
aus.Entwickler Wählen Sie Keyser Soze (keyser@example.com)
aus.Callback URL und Hinweise Leer lassen - Wählen Sie im Bereich Anmeldedaten im Menü Ablauf die Option Nie aus. Die Anmeldedaten für diese Anwendung laufen nie ab.
- Klicken Sie unter Produkte auf Produkt hinzufügen.
- Wählen Sie helloworld_apikey-Product aus.
- Klicken Sie auf Hinzufügen.
- Klicken Sie rechts oben neben dem Abschnitt App-Details auf Erstellen, um Ihre Arbeit zu speichern.
API-Schlüssel abrufen
So rufen Sie den API-Schlüssel ab:
- Klicken Sie auf der Seite Apps (Veröffentlichen > Apps) auf keyser_app.
Klicken Sie auf der Seite keyser_app im Abschnitt Anmeldedaten neben Schlüssel auf Anzeigen. Beachten Sie, dass der Schlüssel im Abschnitt Produkt mit helloworld_apikey verknüpft ist.
.- Wählen Sie den Schlüssel aus und kopieren Sie ihn. Sie benötigen sie im nächsten Schritt.
API mit einem Schlüssel aufrufen
Mit dem API-Schlüssel können Sie jetzt den API-Proxy aufrufen. Geben Sie Folgendes in Ihren Webbrowser ein. Ersetzen Sie ORG_NAME durch Ihren Edge-Organisationsnamen und unten den API-Schlüssel für API_KEY. Der Abfrageparameter darf keine zusätzlichen Leerzeichen enthalten.
http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY
Wenn Sie jetzt den API-Proxy aufrufen, sollten Sie die folgende Antwort erhalten: Hello, Guest!
Glückwunsch! Sie haben einen API-Proxy erstellt und ihn dadurch geschützt, dass im Aufruf ein gültiger API-Schlüssel enthalten sein muss.
Im Allgemeinen ist es nicht empfehlenswert, einen API-Schlüssel als Abfrageparameter zu übergeben. Sie sollten es stattdessen im HTTP-Header übergeben.
Best Practice: Schlüssel im HTTP-Header übergeben
In diesem Schritt ändern Sie den Proxy, sodass in einem Header namens x-apikey
nach dem API-Schlüssel gesucht wird.
- API-Proxy bearbeiten. Wählen Sie Develop > API Proxies > helloworld_apikey aus und wechseln Sie zur Ansicht Develop.
-
Wählen Sie die Richtlinie API-Schlüssel bestätigen aus und ändern Sie die Richtlinien-XML, damit die Richtlinie in
header
und nicht inqueryparam
gesucht wird:<APIKey ref="request.header.x-apikey"/>
- Speichern Sie den API-Proxy, um die Änderung bereitzustellen.
-
Führen Sie den folgenden API-Aufruf mit cURL aus, um den API-Schlüssel als Header namens
x-apikey
zu übergeben. Vergessen Sie nicht, diesen durch den Namen Ihrer Organisation zu ersetzen.curl -v -H "x-apikey: API_KEY" http://ORG_NAME-test.apigee.net/helloapikey
Damit die Änderung vollständig abgeschlossen werden kann, müssen Sie außerdem die „AssignMessage“-Richtlinie so konfigurieren, dass der Header anstelle des Abfrageparameters entfernt wird. Beispiel:
<Remove> <Headers> <Header name="x-apikey"/> </Headers> </Remove>
Weitere Informationen
Folgende Themen beziehen sich direkt auf diese Anleitung:
- API-Produkte verwalten
- API-Schlüssel
- App-Entwickler registrieren
- Anwendungen registrieren und API-Schlüssel verwalten
- VerifyAPIKey-Richtlinie
- AssignMessage-Richtlinie
Etwas genauer, der Schutz von APIs mit API-Schlüsseln ist nur ein Teil der Geschichte. Häufig umfasst der API-Schutz zusätzliche Sicherheitsmaßnahmen wie OAuth.
OAuth ist ein offenes Protokoll, das kurz gesagt Anmeldedaten (z. B. Nutzername und Passwort) gegen Zugriffstoken austauscht. Zugriffstokens sind lange, zufällige Strings, die über eine Nachrichtenpipeline weitergegeben werden können, auch von Anwendung zu Anwendung, ohne die ursprünglichen Anmeldedaten zu beeinträchtigen. Zugriffstokens haben oft eine kurze Lebensdauer, sodass ständig neue generiert werden.