Berechtigungstyp der Clientanmeldedaten implementieren

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation
weitere Informationen

Mit dem Berechtigungstyp der Clientanmeldedaten sendet eine Anwendung ihre eigenen Anmeldedaten (die Client-ID und den Clientschlüssel) an einen Endpunkt in Apigee Edge, der so eingerichtet ist, dass ein Zugriffstoken generiert wird. Wenn die Anmeldedaten gültig sind, gibt Edge ein Zugriffstoken an die Clientanwendung zurück.

Über dieses Thema

In diesem Thema finden Sie eine allgemeine Beschreibung des Autorisierungstyps der OAuth 2.0-Clientanmeldedaten und erfahren, wie dieser Ablauf in Apigee Edge implementiert wird.

Anwendungsfälle

Dieser Berechtigungstyp wird in der Regel verwendet, wenn die Anwendung auch der Ressourceninhaber ist. Beispielsweise kann es sein, dass eine Anwendung auf einen cloudbasierten Back-End-Speicherdienst zugreifen muss, um Daten zu speichern und abzurufen, die sie für ihre Arbeit verwendet, und nicht auf Daten, die speziell dem Endnutzer gehören. Der Gewährungsablauf für diesen Berechtigungstyp findet ausschließlich zwischen zwischen einer Clientanwendung und dem Autorisierungsserver statt. Ein Endnutzer ist nicht am Gewährungsablauf dieses Berechtigungstyps beteiligt.

Rollen

Rollen geben die "Akteure" an, die an dem OAuth-Ablauf beteiligt sind. Sehen wir uns eine kurze Übersicht zu den Rollen der Clientanmeldedaten an, um die Interaktion mit Apigee Edge zu verdeutlichen. Eine vollständige Beschreibung der OAuth 2.0-Rollen finden Sie in der IETF OAuth 2.0-Spezifikation.

  • Clientanwendung: Die Anwendung, die Zugriff auf die geschützten Ressourcen des Nutzers benötigt. Bei diesem Ablauf wird die Anwendung in der Regel auf dem Server und nicht lokal auf dem Laptop oder Gerät des Nutzers ausgeführt.
  • Apigee Edge - In diesem Ablauf ist Apigee Edge der OAuth-Autorisierungsserver. Seine Aufgabe besteht darin, Zugriffstokens zu generieren, Zugriffstoken zu validieren und autorisierte Anfragen für geschützte Ressourcen an den Ressourcenserver zu übergeben.
  • Ressourcenserver: Der Back-End-Dienst, der die geschützten Daten speichert, für die die Client-App eine Zugriffsberechtigung benötigt. Wenn Sie API-Proxys schützen, die in Apigee Edge gehostet werden, ist Apigee Edge auch der Ressourcenserver.

Codebeispiel

Auf GitHub finden Sie eine vollständige, funktionsfähige Beispielimplementierung für den Berechtigungstyp der Clientanmeldedaten. Unter Weitere Ressourcen erhalten Sie Links zu weiteren Beispielen.

Flussdiagramm

Das folgende Flussdiagramm veranschaulicht das Zusammenspiel zwischen den Clientanmeldedaten mit Apigee Edge als Autorisierungsserver. Im Allgemeinen ist Edge auch der Ressourcenserver in diesem Ablauf, d. h. API-Proxys sind die geschützten Ressourcen.


Schritte für den Fluss der Clientanmeldedaten

Im Folgenden finden Sie eine Zusammenfassung der Schritte, die zur Implementierung des Berechtigungstyps für die Clientanmeldedaten erforderlich sind, bei dem Apigee Edge als Autorisierungsserver verwendet wird. Beachten Sie, dass die Clientanwendung in diesem Ablauf einfach ihre Client-ID und den Clientschlüssel darstellt. Wenn beide gültig sind, gibt Apigee Edge ein Zugriffstoken zurück.

Voraussetzung: Die Clientanwendung muss bei Apigee Edge registriert sein, um die Client-ID und den Clientschlüssel zu erhalten. Weitere Informationen finden Sie unter Clientanwendungen registrieren.

1. Client fordert Zugriffstoken an

Um ein Zugriffstoken zu erhalten, sendet der Client einen API-Aufruf an Edge mit den Werten für Client-ID und Clientschlüssel, die von einer registrierten Entwickleranwendung abgerufen wurden. Darüber hinaus muss der Parameter "grant_type=client_credentials" als Abfrageparameter übergeben werden. Sie können jedoch die OAuthV2-Richtlinie so konfigurieren, dass sie diesen Parameter im Anfrageheader oder im Anfragetext akzeptiert. Weitere Informationen finden Sie unter OAuthV2-Richtlinie.

Beispiel:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'

Hinweis: Obwohl Sie die Werte "client_id" und "client_secret" wie oben beschrieben als Abfrageparameter übergeben können, ist es sinnvoll, sie im Autorisierungsheader als base64-URL-codierten String zu übergeben. Dazu müssen Sie ein base64-Codierungstool oder Dienstprogramm verwenden, um die beiden Werte, getrennt durch einen Doppelpunkt, zu codieren. Beispiel: aBase64EncodeFunction(clientidvalue:clientsecret). Das obige Beispiel würde dann so codiert werden:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Beachten sie, dass die beiden Werte durch einen Doppelpunkt getrennt sind.

Das Ergebnis der base64-Codierung des obigen Strings lautet: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Stellen Sie dann die Tokenanfrage wie folgt:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='

2. Edge validiert die Anmeldedaten

Beachten Sie, dass der API-Aufruf an den /accesstoken-Endpunkt gesendet wird. An diesen Endpunkt ist eine Richtlinie angehängt, die die Anmeldedaten der Anwendung validiert. Das heißt, die Richtlinie vergleicht die eingereichten Schlüssel mit den Schlüsseln, die Apigee Edge bei der Registrierung der Anwendung erstellt hat. Weitere Informationen zu OAuth-Endpunkten auf Edge finden Sie unter OAuth-Endpunkte und -Richtlinien konfigurieren.

3. Edge gibt eine Antwort zurück

Wenn die Anmeldedaten in Ordnung sind, gibt Edge ein Zugriffstoken an den Client zurück. Andernfalls wird ein Fehler zurückgegeben.

4. Client ruft die geschützte API auf

Mit dem gültigen Zugriffstoken kann der Client jetzt Aufrufe an die geschützte API senden. In diesem Szenario werden Anfragen an Apigee Edge (den Proxy) gesendet. Edge ist für die Validierung des Zugriffstokens verantwortlich, bevor der API-Aufruf an den Zielressourcenserver übergeben wird. Ein Beispiel dazu finden Sie nachfolgend unter Geschützte API aufrufen.

Abläufe und Richtlinien konfigurieren

Als Autorisierungsserver verarbeitet Edge Anfragen für Zugriffstokens. API-Entwickler müssen einen Proxy mit einem benutzerdefinierten Ablauf erstellen, um Tokenanfragen zu verarbeiten und um eine OAuthV2-Richtlinie hinzuzufügen bzw. zu konfigurieren. In diesem Abschnitt wird erläutert, wie dieser Endpunkt konfiguriert wird.

Benutzerdefinierten Ablauf konfigurieren

Am einfachsten lässt sich die Konfiguration des API-Proxy-Ablaufs durch Darstellung der XML-Ablaufdefinition veranschaulichen. Im Folgenden finden Sie ein Beispiel für einen API-Proxy-Ablauf, der zur Verarbeitung einer Zugriffstokenanfrage entwickelt wurde. Wenn beispielsweise eine Anfrage eingeht und das Pfadsuffix mit /accesstoken übereinstimmt, wird die Richtlinie GetAccessToken ausgelöst. Unter OAuth-Endpunkte und -Richtlinien konfigurieren erhalten Sie einen kurzen Überblick über die Schritte, die zum Erstellen eines benutzerdefinierten Ablaufs wie diesem erforderlich sind.

<Flows>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

Nachfolgend wird beschrieben, wie Sie eine Richtlinie an den Endpunkt anhängen. Unter OAuth-Endpunkte und -Richtlinien konfigurieren finden Sie einen kurzen Überblick über die Schritte zum Hinzufügen einer OAuthV2-Richtlinie an einen Proxyendpunkt.

GetAccessToken

Diese Richtlinie wird an den Pfad /accesstoken angehängt. Dabei wird die OAuthV2-Richtlinie für den angegebenen GenerateAccessToken-Vorgang verwendet.

<OAuthV2 name="GetAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse/>
</OAuthV2>

Der API-Aufruf zum Abrufen des Zugriffstokens ist ein POST und enthält einen Autorisierungsheader mit der base64-codierten client_id + client+secret und dem Abfrageparameter gewähren_type=client_credentials. Außerdem können optionale Parameter für Bereich und Status hinzugefügt werden. Beispiel:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

Richtlinie zum Prüfen des Zugriffstokens anhängen

Zum Schutz Ihrer API mit OAuth 2.0-Sicherheit müssen Sie eine OAuthV2-Richtlinie mit dem VerifyAccessToken-Vorgang hinzufügen. Diese Richtlinie prüft, ob eingehende Anfragen ein gültiges Zugriffstoken haben. Wenn das Token gültig ist, verarbeitet Edge die Anfrage. Wenn sie nicht gültig ist, gibt Edge einen Fehler zurück. Die grundlegenden Schritte dazu finden Sie unter Zugriffstoken prüfen.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

Geschützte API aufrufen

Um eine API aufzurufen, die mit OAuth 2.0-Sicherheit geschützt ist, müssen Sie ein gültiges Zugriffstoken angeben. Das richtige Muster ist, das Token in einem Autorisierungs-Header so anzugeben: Beachten Sie, dass das Zugriffstoken auch als "Inhabertoken" bezeichnet wird.

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282 

Weitere Informationen finden Sie unter Zugriffstoken senden.

Zusätzliche Ressourcen

  • Apigee bietet Onlineschulungen für API-Entwickler, einschließlich eines Kurses zur API-Sicherheit, die OAuth enthält.
  • OAuthV2-Richtlinie – Bietet viele Beispiele, wie Sie Anfragen an den Autorisierungsserver senden und die OAuthV2-Richtlinie konfigurieren können.