API mit OAuth sichern

Sie lesen die Dokumentation zu Apigee X.
Apigee Edge-Dokumentation aufrufen

In dieser Anleitung wird Folgendes erläutert:

  • Beispiel-API-Proxy herunterladen und bereitstellen
  • Sie erstellen einen OAuth-geschützten API-Proxy.
  • Erstellen Sie ein Produkt, einen Entwickler und eine App.
  • Anmeldedaten für ein OAuth-Zugriffstoken austauschen.
  • API mit einem Zugriffstoken aufrufen

OAuth ist ein Autorisierungsprotokoll, mit dem Anwendungen im Namen der Nutzer auf Informationen zugreifen können, ohne dass Nutzer ihre Nutzernamen und Passwörter ändern müssen.

Mit OAuth werden Sicherheitsanmeldedaten (z. B. Nutzername/Passwort oder Schlüssel/Secret) gegen ein Zugriffstoken ausgetauscht. Beispiel:

joe:joes_password (username:password) oder
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (key:secret)

könnte dann etwa so aussehen:

b0uiYwjRZLEo4lEu7ky2GGxHkanN

Das Zugriffstoken besteht aus einer zufälligen Zeichenfolge und ist temporär (es sollte nach relativ kurzer Zeit ablaufen), sodass die Weitergabe zur Authentifizierung eines Benutzers in einem App-Workflow viel sicherer ist als die Weitergabe der tatsächlichen Anmeldeinformationen.

In der OAuth 2.0-Spezifikation werden verschiedene Mechanismen für die Verteilung von Zugriffstokens für Anwendungen definiert. Die eine OAuth 2.0-Zustimmungsart wird als „Client-Anmeldedaten“ bezeichnet. In diesem Gewährungstyp werden OAuth-Zugriffstokens im Austausch für Clientanmeldedaten generiert. Das sind Schlüssel-/Consumer-Secret-Paare, wie im obigen Beispiel.

Der Typ der Clientanmeldedaten wird in Apigee mithilfe von Richtlinien in API-Proxys implementiert. Ein typischer OAuth-Ablauf umfasst zwei Schritte:

  • Call API Proxy proxy 1, um ein OAuth-Zugriffstoken aus Clientanmeldedaten zu generieren. Eine OAuth v2.0-Richtlinie für den API-Proxy übernimmt dies.
  • Call API proxy 2, um das OAuth-Zugriffstoken in einem API-Aufruf zu senden Der API-Proxy überprüft das Zugriffstoken mithilfe einer OAuth v2.0-Richtlinie.

Tokengenerierenden API-Proxy herunterladen und bereitstellen

In diesem Schritt erstellen Sie den API-Proxy, der ein OAuth-Zugriffstoken aus einem Nutzerschlüssel und einem Consumer-Secret generiert, das in einem API-Aufruf gesendet wird. Apigee bietet einen API-Beispielproxy, der dies ausführt. Sie laden den Proxy jetzt herunter und stellen ihn bereit, um ihn später in der Anleitung zu verwenden. (Sie können diesen API-Proxy problemlos selbst erstellen. Die Schritte zum Herunterladen und Bereitstellen sind der Einfachheit halber und zeigen, wie einfach es ist, Proxys freizugeben, die bereits erstellt wurden.)

  1. Laden Sie den Beispiel-API-Proxy „OAuth“ herunter. ZIP-Datei in ein beliebiges Verzeichnis in Ihrem Dateisystem.
  2. Wechseln Sie zur Apigee-Benutzeroberfläche und melden Sie sich an.
  3. Wählen Sie in der linken Navigationsleiste Develop > API Proxies aus.
  4. Klicken Sie auf Neu erstellen.
    Schaltfläche „Proxy 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 das Drop-down Revision und wählen Sie die Überarbeitungsnummer aus, um den Proxy bereitzustellen.

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

OAuth-Ablauf und Richtlinie ansehen

Sehen wir uns genauer 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. Dies wird als „bedingter Ablauf“ bezeichnet. Die im Element <Condition> definierte Bedingung gibt an, dass der API-Proxyaufruf für die Ressource /accesstoken ausgeführt wird und das Anfrageverb POST lautet, und führen dann folgenden Befehl aus: Die Richtlinie GenerateAccessTokenClient, die das Zugriffstoken generiert.

  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 in die Codeansicht geladen:

    <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 <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-Zugriffstoken zu generieren. Zuerst müssen Sie jedoch noch ein paar zusätzliche Schritte ausführen:

  • Erstellen Sie den API-Proxy, der mit OAuth 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.

OAuth-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-Zugriffstoken übergeben.

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

  1. Wählen Sie in der linken Navigationsleiste Develop > API Proxies aus.
  2. Klicken Sie auf Neu erstellen.
    Schaltfläche „Proxy 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 Sie /hellooauth2 zu .

    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
  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.
  8. Wählen Sie auf der Seite Zusammenfassung unter Optionale Bereitstellung eine Umgebung aus und klicken Sie auf Erstellen.
  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.

  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-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-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-Token.

API-Produkt hinzufügen

So fügen Sie ein API-Produkt über die Apigee-Benutzeroberfläche hinzu:

  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-Bereiche Diese Anleitung ignorieren.
  4. Klicken Sie unter Vorgänge auf Projekt 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-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. nigel@example.com
  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 (nigel@example.com) 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-Zugriffstoken ausgetauscht werden.

  1. Achten Sie darauf, dass die Seite nig_app angezeigt wird. Wenn nicht, klicken Sie auf der Seite „Apps“ Veröffentlichen > Apps auf nigel_app.
  2. Klicken Sie auf der Seite „nigel_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-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-Zugriffstoken an den Aufruf übergeben.

curl -v -k https://EXTERNAL_IP/hellooauth2

Dabei ist EXTERNAL_IP die Adresse Ihrer Internet-IP-Adresse, wie bei der Installation von Apigee definiert. Siehe Routing konfigurieren.

Da der API-Proxy die Richtlinie OAuth v2.0 Access Token überprüfen auf ein gültiges OAuth-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-Zugriffstoken können diese API aufrufen.

OAuth-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-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://EXTERNAL_IP/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id={key}&client_secret={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" : "nigel@example.com",
  "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-Zugriffstoken erhalten. Kopieren Sie den Wert des Zugriffs-Tokens (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-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-Richtlinie ausgeführt wurde. Sie hat Ihren Consumer-Key und Ihr Consumer-Secret verifiziert und gegen ein OAuth-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 (entfernen Sie die geschweiften Klammern).

curl https://EXTERNAL_IP/hellooauth2 -H "Authorization: Bearer {access-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-Zugriffstoken in den Aufruf eingefügt wurde.

Weitere Informationen