API mit OAuth 2.0 sichern

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

In dieser Anleitung erfahren Sie, wie Sie einen API-Proxy mithilfe eines OAuth 2.0-Zugriffstokens sichern.

Hinweis

Für diese Anleitung benötigen Sie Zugriff auf eine Apigee-Organisation, für die Sie folgende Berechtigungen haben:

• API-Proxys erstellen und bereitstellen
• API-Produkte erstellen
• Entwickler-Apps erstellen

Sie müssen auch einen ordnungsgemäß konfigurierten Hostnamen für die Umgebungsgruppe haben, mit dem Sie Apigee API-Proxyaufrufe ausführen können. Wenn Sie nicht sicher sind, welcher Hostname für die Umgebungsgruppe verwendet werden soll, wenden Sie sich an Ihren Apigee-Administrator.

Stellen Sie den OAuth 2.0-Proxy bereit

Wir bieten einen API-Proxy auf GitHub, der zum Generieren von OAuth 2.0-Zugriffstokens konfiguriert ist. Führen Sie die folgenden Schritte aus, um diesen API-Proxy in Ihrer Umgebung herunterzuladen und bereitzustellen:

1. Laden Sie den Beispiel-API-Proxy oauth in ein Verzeichnis in Ihrem Dateisystem herunter.
2. Wechseln Sie zur Apigee-Benutzeroberfläche und melden Sie sich an und wählen Sie Ihre Apigee-Organisation aus.
3. Wählen Sie in der linken Navigationsleiste Develop > API Proxies aus.
   Hinweis: Bevor Sie fortfahren, suchen Sie Ihre Liste der API-Proxys oder suchen Sie sie. Wenn Sie bereits einen OAuth haben, klicken Sie darauf und gehen Sie zum nächsten Abschnitt über. Vergewissern Sie sich, dass der Proxy so konfiguriert ist wie dort beschrieben. Sollte das nicht der Fall sein, können Sie ihn entweder löschen und mit den folgenden Schritten fortfahren oder die Konfiguration entsprechend ändern.
4. Klicken Sie auf Neu erstellen.
   
5. Wählen Sie im Assistenten „Create Proxy“ die Option Upload proxy bundle aus.
6. Wählen Sie die heruntergeladene Datei oauth.zip aus und klicken Sie auf Weiter.
7. Klicken Sie auf Create.
8. Klicken Sie nach Abschluss des Builds auf Edit Proxy, um den neuen Proxy im API-Proxy-Editor aufzurufen.
9. Klicken Sie auf Bereitstellen.
10. Wählen Sie die Überarbeitung und Umgebung für die Bereitstellung aus. Das Feld Dienstkonto können Sie leer lassen.
11. Klicken Sie auf Bereitstellen.

Sie haben einen API-Proxy zur Generierung von Zugriffstokens heruntergeladen und in Ihrer Apigee-Organisation bereitgestellt.

OAuth-Ablauf 2.0 und Richtlinie ansehen

Nehmen Sie sich einen Moment Zeit, um sich die OAuth 2.0-Richtlinienkonfiguration anzusehen.

Hinweis: Apigee wird zukünftig eine neue Version des Proxy-Editors bereitstellen, die die Verwaltung von Proxys vereinfachen wird.

In den Anleitungen auf den ersten beiden Tabs unten wird erläutert, wie Sie entweder den neuen Proxy-Editor oder den klassischen Proxy-Editor verwenden.

Neuer Proxy-Editor

Als Nächstes sehen wir uns an, was der API-Proxy enthält.

1. Klicken Sie im API-Proxy-Editor auf den Tab Develop.

   

   Im linken Bereich sehen Sie zwei Richtlinien. Außerdem werden im Abschnitt „Proxyendpunkte“ zwei POST-Abläufe angezeigt.

2. Klicken Sie unter Proxyendpunkte auf AccessTokenClientCredential. Im Texteditor wird der XML-Code für den bedingten Ablauf AccessTokenClientCredential angezeigt:

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>
   

   Ein Ablauf ist ein Verarbeitungsschritt in einem API-Proxy. In diesem Fall wird der Ablauf ausgelöst, wenn eine bestimmte Bedingung erfüllt ist. Dies wird als „bedingter Ablauf“ bezeichnet. Die im Element <Condition> definierte Bedingung gibt an, dass die GenerateAccessTokenClient-Richtlinie, die das Zugriffstoken generiert, dann ausgeführt wird, wenn der API-Proxyaufruf an die /accesstoken-Ressource ausgeführt wird und das Anfrageverb POST lautet.

3. Betrachten wir nun die Richtlinie, die der bedingte Ablauf auslöst. Klicken Sie auf die Richtlinie GenerateAccessTokenClient im Bereich Anfrage:

Klassischer Proxy-Editor

Als Nächstes sehen wir uns an, was der API-Proxy enthält.

1. Klicken Sie im API-Proxy-Editor auf den Tab Develop. Im linken Navigationsbereich sehen Sie zwei Richtlinien. Außerdem werden im Abschnitt „Proxyendpunkte“ zwei POST-Abläufe angezeigt.

2. Klicken Sie unter "Proxyendpunkte" auf AccessTokenClientCredential.
   

   In der XML-Codeansicht sehen Sie ein Flow namens AccessTokenClientCredential:

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>
   

   Ein Ablauf ist ein Verarbeitungsschritt in einem API-Proxy. In diesem Fall wird der Ablauf ausgelöst, wenn eine bestimmte Bedingung erfüllt ist. Die im Element <Condition> definierte Bedingung gibt an, dass die GenerateAccessTokenClient-Richtlinie, die das Zugriffstoken generiert, dann ausgeführt wird, wenn der API-Proxyaufruf an die /accesstoken-Ressource ausgeführt wird und das Anfrageverb POST lautet.

3. Betrachten wir nun die Richtlinie, die der bedingte Ablauf auslöst. Klicken Sie im Flussdiagramm auf das Richtliniensymbol GenerateAccessTokenClient.

   

Die folgende XML-Konfiguration wird angezeigt:

<OAuthV2 name="GenerateAccessTokenClient">
    <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
    <Operation>GenerateAccessToken</Operation>
    <!-- This is in milliseconds, so expire in an hour -->
    <ExpiresIn>3600000</ExpiresIn>
    <SupportedGrantTypes>
        <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with no user authentication -->
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

Die Konfiguration umfasst Folgendes:

• Der <Operation>, der einer von mehreren vordefinierten Werten sein kann, legt die Funktionsweise der Richtlinie fest. In diesem Fall wird ein Zugriffstoken generiert.
• Das Token läuft 1 Stunde (3.600.000 Millisekunden) nach Erstellung ab.
• In <SupportedGrantTypes> wird erwartet, dass der verwendete OAuth 2.0 <GrantType> client_credentials ist (Austausch eines Verbraucherschlüssels und -geheimnisses gegen ein OAuth-Token).
• Das zweite <GrantType>-Element informiert die Richtlinie darüber, wo der API-Aufruf für den „type“-Parameterparameter gemäß der OAuth 2.0-Spezifikation zu suchen ist. Sie sehen dies später im API-Aufruf. Die Gewährungsart kann auch im HTTP-Header (request.header.grant_type) oder als Formularparameter (request.formparam.grant_type) gesendet werden.

Derzeit müssen Sie mit dem API-Proxy nichts weiter tun. In späteren Schritten benötigen Sie diesen API-Proxy, um ein OAuth 2.0-Zugriffstoken zu generieren. Zuerst müssen Sie jedoch noch ein paar zusätzliche Schritte ausführen:

• Erstellen Sie den API-Proxy, der mit OAuth 2.0 gesichert werden soll.
• Erstellen Sie ein paar weitere Artefakte, die zu dem Consumer-Key und Consumer-Secret führen, das Sie gegen ein Zugriffstoken austauschen müssen.

Hinweis: Der Ablauf und die Richtlinie RefreshAccessToken im API-Proxy werden in dieser Anleitung nicht verwendet und mit dem OAuth 2.0 Client Credentials Grant Type nicht unterstützt.

Geschützten API-Proxy erstellen

Jetzt erstellen Sie den API-Proxy, der geschützt werden soll. Dies ist der API-Aufruf, der einen gewünschten Inhalt zurückgibt. In diesem Fall ruft der API-Proxy den fiktiven Zieldienst von Apigee auf, um Ihre IP-Adresse zurückzugeben. Sie sehen diese Option jedoch nur, wenn Sie mit Ihrem API-Aufruf ein gültiges OAuth 2.0-Zugriffstoken übergeben.

Der API-Proxy, den Sie hier erstellen, enthält eine Richtlinie, die in der Anfrage nach einem OAuth 2.0-Token sucht.

1. Wählen Sie in der linken Navigationsleiste Develop > API Proxies aus.
2. Klicken Sie auf Neu erstellen.
   
3. Wählen Sie im Assistenten zum Erstellen eines Proxys die Option Reverse proxy (am häufigsten) aus.
4. Konfigurieren Sie den Proxy so:
   

   In diesem Feld	tun Sie Folgendes
   Proxy-Name	Eingeben: helloworld_oauth2
   Projektbasispfad	Ändern zu: /hellooauth2 Der Projektbasispfad ist Teil der URL, die für Anfragen an den API-Proxy verwendet wird.
   Vorhandene API	Eingeben: https://mocktarget.apigee.net/ip Dies definiert die Ziel-URL, die Apigee für eine Anfrage an den API-Proxy aufruft.
   Beschreibung	Eingeben: hello world protected by OAuth 2.0

5. Klicken Sie auf Next.
6. Auf der Seite Common policies:

   In diesem Feld	tun Sie Folgendes
   Security: Authorization	Wählen Sie aus. OAuth 2.0 Diese Optionen sind sehr praktisch. Sie fügen dem API-Proxy automatisch zwei Richtlinien hinzu und erstellen ein API-Produkt.

7. Klicken Sie auf Next (Weiter).
8. Wählen Sie auf der Seite Zusammenfassung unter Optionale Bereitstellung eine Umgebung aus und klicken Sie auf Erstellen und bereitstellen.
9. Klicken Sie auf Proxy bearbeiten, um die Übersichtsseite für den API-Proxy aufzurufen.
   Der API-Proxy wird automatisch für Sie bereitgestellt. Es kann einen Moment dauern, bis die Bereitstellung abgeschlossen ist.

Richtlinien ansehen

Sehen wir uns genauer an, was Sie erstellt haben.

Neuer Proxy-Editor

1. Klicken Sie im API-Proxy-Editor auf den Tab Develop. Sie werden sehen, dass dem Anfrageablauf des API-Proxys zwei Richtlinien hinzugefügt wurden:
   • OAuth v2.0-Zugriffstoken überprüfen: Der API-Aufruf wird überprüft, um sicherzustellen, dass ein gültiges OAuth 2.0-Token vorhanden ist.
   • Header-Autorisierung entfernen: Eine Richtlinie für das Zuweisen von Nachrichten, die das Zugriffstoken nach der Überprüfung entfernt, damit sie nicht an den Zieldienst übergeben wird. Wenn der Zieldienst das OAuth 2.0-Zugriffstoken benötigt, würden Sie diese Richtlinie nicht verwenden.

2. Klicken Sie im rechten Bereich auf das Symbol OAuth v2.0-Zugriffstoken überprüfen und prüfen Sie die XML darunter im Texteditor.

Klassischer Proxy-Editor

1. Klicken Sie im API-Proxy-Editor auf den Tab Develop. Sie werden sehen, dass dem Anfrageablauf des API-Proxys zwei Richtlinien hinzugefügt wurden:
   • OAuth v2.0-Zugriffstoken überprüfen: Der API-Aufruf wird überprüft, um sicherzustellen, dass ein gültiges OAuth 2.0-Token vorhanden ist.
   • Header-Autorisierung entfernen: Eine Richtlinie für das Zuweisen von Nachrichten, die das Zugriffstoken nach der Überprüfung entfernt, damit sie nicht an den Zieldienst übergeben wird. Wenn der Zieldienst das OAuth 2.0-Zugriffstoken benötigt, würden Sie diese Richtlinie nicht verwenden.

2. Klicken Sie in der Ablaufansicht auf das Symbol OAuth v2.0-Zugriffstoken überprüfen und prüfen Sie die XML darunter im Codebereich.

   

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Beachten Sie, dass <Operation> VerifyAccessToken lautet. Der Vorgang definiert, was die Richtlinie tun soll. In diesem Fall prüft sie in der Anfrage nach einem gültigen OAuth 2.0-Token.

API-Produkt hinzufügen

Um ein OAuth 2.0-Zugriffstoken zu erhalten, müssen Sie drei Apigee-Entitäten erstellen: ein API-Produkt, einen Entwickler und eine Entwickler-App. Erstellen Sie zuerst das API-Produkt:

1. Wählen Sie Publish > API Products aus.
2. Klicken Sie auf +Erstellen.
3. Geben Sie die Produktdetails für Ihr API-Produkt ein.
   

   Feld	Beschreibung
   Name	Interner Name des API-Produkts. Geben Sie im Namen keine Sonderzeichen an. Hinweis: Sobald der API-Produkt erstellt wurde, können Sie den Namen nicht mehr ändern.
   Anzeigename	Anzeigename für das API-Produkt. Der Anzeigename wird in der Benutzeroberfläche verwendet und kann jederzeit bearbeitet werden. Wenn keine Angabe erfolgt, wird der Wert "Name" verwendet. Dieses Feld wird automatisch mit dem Wert "Name" ausgefüllt. können Sie den Inhalt bearbeiten oder löschen. Der Anzeigename kann Sonderzeichen enthalten.
   Beschreibung	Beschreibung des API-Produkts.
   Umgebung	Umgebungen, auf die das API-Produkt Zugriff gewährt. Wählen Sie die Umgebung aus, in der Sie den API-Proxy bereitgestellt haben.
   Zugriff	Wählen Sie Public aus.
   Zugriffsanfragen automatisch genehmigen	Aktivieren Sie die automatische Genehmigung von Schlüsselanfragen für dieses API-Produkt aus einer beliebigen Anwendung.
   Kontingent	Für diese Anleitung ignorieren.
   Erlaubte OAuth 2.0-Bereiche	Für diese Anleitung ignorieren.

4. Klicken Sie unter Vorgänge auf Vorgang hinzufügen.
5. Wählen Sie im Feld „API-Proxy“ den soeben erstellten API-Proxy aus.
6. Geben Sie im Feld „Pfad“ „/“ ein. Ignorieren Sie die anderen Felder.
7. Klicken Sie auf Speichern, um den Vorgang zu speichern.
8. Klicken Sie auf Speichern, um das API-Produkt zu speichern.

Einen Entwickler und eine App zur Organisation hinzufügen

Als Nächstes simulieren Sie den Workflow eines Entwicklers, der sich registriert, um Ihre APIs zu verwenden. Im Idealfall registrieren Entwickler sich und ihre Apps über Ihr Entwicklerportal. In diesem Schritt fügen Sie jedoch einen Entwickler und eine Anwendung als Administrator hinzu.

Entwickler haben eine oder mehrere Anwendungen, die Ihre APIs aufrufen. Jede Anwendung erhält einen eindeutigen Consumer-Key und ein Consumer-Secret. Mit diesem Schlüssel/Secret-pro-App erhalten Sie außerdem den API-Anbieter, eine genauere Kontrolle über den Zugriff auf Ihre APIs sowie detailliertere Analysen von API-Traffic, da Apigee weiß, welcher Entwickler und welche App zu welchem OAuth 2.0-Token gehört.

Entwickler erstellen

Erstellen wir nun einen Entwickler mit dem Namen Nigel Tufnel.

1. Wählen Sie im Menü Veröffentlichen > Entwickler aus.
2. Klicken Sie auf + Entwickler.
3. Geben Sie im Fenster "New Developer" Folgendes ein:
   

   In diesem Feld	Eingeben
   Vorname	Nigel
   Nachname	Tufnel
   Nutzername	nigel
   In Email geben Sie Ihre E-Mail-Adresse ein.	[e-mail]

4. Klicken Sie auf Speichern.

App registrieren

Erstellen wir nun eine App für Nigel.

1. Wählen Sie Veröffentlichen > Apps aus.
2. Klicken Sie auf + App.
3. Geben Sie im Fenster „Neue Entwickler-App“ Folgendes ein:
   

   In diesem Feld	tun Sie Folgendes
   Name und Anzeigename	Eingeben: nigel_app
   Entwickler	Klicken Sie auf Entwickler und wählen Sie Nigel Tufnel ([e-mail]) aus.
   Callback URL und Hinweise	Leer lassen

4. Klicken Sie unter Produkte auf Produkt hinzufügen.
5. Fügen Sie das gerade erstellte API-Produkt hinzu.
6. Klicken Sie auf Create.

Consumer-Key und Consumer-Secret abrufen

Sie erhalten nun den Consumer-Key und das Consumer-Secret, die gegen ein OAuth 2.0-Zugriffstoken ausgetauscht werden.

1. Achten Sie darauf, dass die Seite nig_app angezeigt wird. Wenn nicht, klicken Sie auf der Seite „Apps“ (Publish > Apps) auf nig_app.

2. Klicken Sie auf der Seite „nig_app“ in den Spalten Schlüssel und Secret auf Anzeigen. Beachten Sie, dass der Schlüssel/das Secret mit dem API-Produkt verknüpft sind, das Sie zuvor erstellt haben.

3. Kopieren und kopieren Sie den Schlüssel und das Secret. Fügen Sie sie in eine temporäre Textdatei ein. Sie benötigen sie in einem späteren Schritt, indem Sie den API-Proxy aufrufen, der diese Anmeldedaten gegen ein OAuth 2.0-Zugriffstoken austauschen.

Versuchen Sie, die API aufzurufen, um Ihre IP-Adresse abzurufen (fehlgeschlagen)

Versuchen Sie, den geschützten API-Proxy aufzurufen, den Sie gerade erstellt haben. Beachten Sie, dass Sie kein OAuth 2.0-Zugriffstoken an den Aufruf übergeben.

Dabei ist YOUR ENV_GROUP_HOSTNAME der Hostname der Umgebungsgruppe. Weitere Informationen finden Sie unter Hostname der Umgebungsgruppe finden.

Da der API-Proxy die Richtlinie OAuth v2.0 Access Token überprüfen auf ein gültiges OAuth 2.0-Token prüft, sollte der Aufruf mit der folgenden Meldung fehlschlagen:

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

In diesem Fall ist ein Fehler aufgetreten. Das bedeutet, dass Ihr API-Proxy viel sicherer ist. Nur vertrauenswürdige Anwendungen mit einem gültigen OAuth 2.0-Zugriffstoken können diese API aufrufen.

OAuth 2.0-Zugriffstoken abrufen

Als Nächstes verwenden Sie den Schlüssel und das Secret, die Sie kopiert und in eine Textdatei eingefügt haben, und tauschen sie gegen ein OAuth 2.0-Zugriffstoken ein. Jetzt starten Sie einen API-Aufruf an den importierten API-Beispielproxy OAuth, mit dem ein API-Zugriffstoken generiert wird.

Führen Sie mit diesem Schlüssel und diesem Secret den folgenden cURL-Aufruf durch. Beachten Sie, dass das Protokoll https ist:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

Wenn Sie einen Aufruf wie Postman zum Aufrufen verwenden, werden client_id und client_secret in den Hauptteil der Anfrage eingefügt und müssen x-www-form-urlencoded sein.

Es sollte eine Antwort in folgender Form zurückgegeben werden:

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "[e-mail]",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Sie haben Ihr OAuth 2.0-Zugriffstoken erhalten. Kopieren Sie den Wert des access_token (ohne Anführungszeichen) und fügen Sie ihn in Ihre Textdatei ein. Sie werden ihn gleich verwenden.

Was ist gerade passiert?

Erinnern Sie sich daran, als Sie sich den „bedingten Fluss“ im OAuth-Proxy angesehen haben, der besagt, dass die GenerateAccessTokenClient-OAuth 2.0-Richtlinie, die ein Zugriffstoken generiert, ausgeführt werden muss, wenn die Ressourcen-URI /accesstoken und das Anfrageverb POST gleich sind? Ihr cURL-Befehl erfüllt diese Bedingungen, sodass die OAuth 2.0-Richtlinie ausgeführt wurde. Sie hat Ihren Consumer-Key und Ihr Consumer-Secret verifiziert und gegen ein OAuth 2.0-Token ausgetauscht, das in einer Stunde abläuft.

API mit einem Zugriffstoken aufrufen (erfolgreich)

Mit dem Zugriffstoken können Sie nun den API-Proxy aufrufen. Führen Sie den folgenden cURL-Aufruf aus: Ersetzen Sie den Namen Ihrer Apigee-Organisation und das Zugriffstoken.

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer TOKEN"

Sie sollten nun einen erfolgreichen Aufruf an den API-Proxy anfordern, der Ihre IP-Adresse zurückgibt. Beispiel:

{"ip":"::ffff:192.168.14.136"}

Sie können diesen API-Aufruf für etwa eine Stunde wiederholen, nach deren Ablauf das Zugriffstoken abläuft. Für den Aufruf nach einer Stunde müssen Sie mit den vorherigen Schritten ein neues Zugriffstoken generieren.

Glückwunsch! Sie haben einen API-Proxy erstellt und geschützt, indem ein gültiges OAuth 2.0-Zugriffstoken in den Aufruf eingefügt wurde.

Weitere Informationen

• OAuth 2.0-Startseite
• OAuthV2-Richtlinie
• API-Proxys herunterladen (in diesem Artikel wird gezeigt, wie Sie einen API-Proxy in einer ZIP-Datei wie die von Ihnen heruntergeladene ZIP-Datei bündeln)