Grant-Typ des Autorisierungscode implementieren

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Der Autorisierungscode ist einer der am häufigsten verwendeten OAuth 2.0-Zuweisungstypen. Der Ablauf des Autorisierungscodes ist eine dreibeinige OAuth-Konfiguration. In dieser Konfiguration authentifiziert sich der Nutzer selbst beim Ressourcenserver und gewährt der Anwendung die Berechtigung, auf ihre geschützten Ressourcen zuzugreifen, ohne Nutzername/Passwörter an die Clientanwendung binden zu müssen.

Über dieses Thema

Dieses Thema bietet eine allgemeine Beschreibung und einen Überblick über den Ablauf von OAuth 2.0-Autorisierungsberechtigungen und erklärt, wie dieser Ablauf in Apigee implementiert wird.

Video

In einem kurzen Video erfahren Sie, wie Sie Ihre APIs mit dem Autorisierungstyp OAuth 2.0 sichern.

Anwendungsfälle

Diese Art der Förderung ist für Anwendungen von Drittanbietern gedacht, die keine vertrauenswürdige Geschäftsbeziehung mit dem API-Anbieter haben. Beispielsweise sollten Entwickler, die sich für öffentliche API-Programme registrieren, nicht allgemein vertrauenswürdig sein. Bei diesem Gewährungstyp werden die Anmeldedaten des Nutzers auf dem Ressourcenserver niemals für die Anwendung freigegeben.

Codebeispiel

Im api-platform-samples-Repository von GitHub finden Sie eine vollständige, funktionierende Beispielimplementierung des Autorisierungscodes für Apigee. Sehen Sie sich das OAuth-Advanced-Beispiel im Verzeichnis "api-platform-samples/sample-proxies" an. Weitere Informationen finden Sie in der Datei README.

Flussdiagramm

Das folgende Flussdiagramm veranschaulicht den OAuth-Ablauf des Autorisierungscodes mit Apigee Edge als Autorisierungsserver.

Hinweis: Schauen Sie sich eine größere Version dieses Diagramms an.

Ablaufschritte des Autorisierungscodes

Nachfolgend finden Sie eine Zusammenfassung der Schritte, die zum Implementieren des Berechtigungstyps für den Autorisierungscode erforderlich sind, wobei Apigee als Autorisierungsserver dient. Denken Sie daran, dass der Schlüssel für diesen Ablauf darin besteht, dass der Client die Anmeldedaten des Nutzers auf dem Ressourcenserver nicht sehen kann.

Hinweis: Die folgenden Darstellungen stammen aus der Beispielimplementierung für den Autorisierungscode auf GitHub.

Voraussetzung: Damit die Client-ID und der Clientschlüssel abgerufen werden können, muss die Clientanwendung bei Apigee registriert sein. Weitere Informationen finden Sie unter Clientanwendungen registrieren.

1. Nutzer initiiert den Ablauf

Wenn die Anwendung über einen Ressourcenserver auf die geschützten Ressourcen des Nutzers zugreifen muss (z. B. auf einer Social-Media-Website), wird ein API-Aufruf an Apigee gesendet. Damit wird die Client-ID validiert und, falls sie gültig ist, leitet der Browser des Nutzers zu einer Anmeldeseite weiter, auf der der Nutzer seine Anmeldedaten eingibt. Der API-Aufruf enthält Informationen, die die Clientanwendung bei der Registrierung erhalten hat: die Client-ID und den Weiterleitungs-URI.

2. Nutzer gibt Anmeldedaten ein

Der Nutzer sieht jetzt eine Anmeldeseite, auf der er aufgefordert wird, seine Anmeldedaten einzugeben. Wenn die Anmeldung erfolgreich ist, fahren wir mit dem nächsten Schritt fort.

3. Der Nutzer gibt seine Einwilligung

In diesem Schritt erteilt der Nutzer der App Zugriff auf seine Ressourcen. Das Einwilligungsformular enthält in der Regel Umfangsbereiche, in denen der Nutzer auswählen kann, was die App auf dem Ressourcenserver tun darf. Der Nutzer kann zum Beispiel schreibgeschützte Berechtigungen oder die Berechtigung zum Aktualisieren von Ressourcen durch die App erteilen.

4. Die Anmeldeanwendung sendet eine Apigee-Anfrage.

Wenn die Anmeldung und die Einwilligung erfolgreich sind, sendet die Anmeldeanwendung Daten an den /authorizationcode-Endpunkt von Apigee. Die Daten umfassen den Weiterleitungs-URI, die Client-ID, den Bereich sowie nutzerspezifische Angaben, die Sie angeben möchten, sowie einen Hinweis darauf, dass die Anmeldung erfolgreich war.

Hinweis: Diese Informationen werden von der Client-App nie angezeigt. Sie wird serverseitig verarbeitet und zwischen der Anmeldeanwendung und Apigee ausgehandelt. Ein Beispiel für den sicheren Umgang mit diesem Schritt finden Sie in der Beispielimplementierung für den Autorisierungscode auf GitHub.

5. Apigee generiert einen Autorisierungscode

Wenn Apigee eine GET-Anfrage von der Anmelde-App auf dem /Autorisierungscode-Endpunkt empfängt, geschieht Folgendes: Erstens ermittelt Apigee, ob die Anmeldung erfolgreich war (durch Prüfen des HTTP-Status oder anderer Methoden). Dann prüft Apigee, ob der von der Anmelde-App gesendete Redirect-URI mit dem Redirect-URI übereinstimmt, der bei der Registrierung der App bei Apigee angegeben wurde. Wenn alles in Ordnung ist, generiert Edge einen Autorisierungscode. Beispiel:

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Apigee sendet den Autorisierungscode an den Client zurück

Edge sendet eine 302-Weiterleitung mit dem Auth-Code als Abfrageparameter an den Client.

7. Der Client ruft den Autorisierungscode ab und fordert von Apigee einen Zugriffscode an

Mit einem gültigen Authentifizierungscode kann der Client jetzt ein Zugriffstoken von Apigee anfordern. Dies geschieht durch POSTing der Client-ID und der geheimen Clientschlüssel (die bei der Apigee-Registrierung der App erhalten wurden), des Granttyps und des Umfangs. Durch die Angabe der Client-ID und der geheimen Schlüssel kann Apigee prüfen, ob die Client-App diejenige ist, die registriert wurde. Beispiel:

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. Der Client erhält ein Zugriffstoken

Wenn alles erfolgreich ist, gibt Apigee ein Zugriffstoken an den Client zurück. Das Zugriffstoken unterliegt einem Ablauf. Es ist nur für den Bereich gültig, der vom Nutzer angegeben wurde, wenn es der App erlaubt hat, auf ihre Ressourcen zuzugreifen.

9. Der Client ruft die geschützte API auf.

Mit einem gültigen Zugriffscode kann der Client Aufrufe an die geschützte API senden. In diesem Szenario werden Anfragen an Apigee (den Proxy) gesendet. Apigee ist für die Validierung des Zugriffstokens zuständig, bevor der API-Aufruf an den Zielressourcenserver übergeben wird. Zugriffstokens werden in einem Autorisierungsheader übergeben. Beispiel:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Abläufe und Richtlinien konfigurieren

Als Autorisierungsserver muss Apigee eine Reihe von OAuth-Anfragen verarbeiten: für Zugriffstoken, Authentifizierungscodes, Aktualisierungstokens, Weiterleitungen auf der Anmeldeseite usw. Zur Konfiguration dieser Endpunkte sind zwei grundlegende Schritte erforderlich:

• Benutzerdefinierte Abläufe erstellen
• OAuthV2-Richtlinien hinzufügen und konfigurieren

Benutzerdefinierte Ablaufkonfiguration

In der Regel konfigurieren Sie diesen Berechtigungstyp, sodass jeder Schritt oder Zweig des Ablaufs durch einen Ablauf im Apigee-Proxy definiert wird. Jeder Ablauf hat einen Endpunkt und eine Richtlinie, die die erforderliche OAuth-Aufgabe ausführt, z. B. das Generieren eines Autorisierungscodes oder eines Zugriffstokens. Wie unten in der XML-Datei dargestellt, hat der Endpunkt /oauth/authorizationcode eine zugehörige Richtlinie namens GenerateAuthCode. Dies ist eine OAuthV2-Richtlinie mit dem angegebenen GenerateAuthorizationCode-Vorgang.

Am einfachsten lässt sich die Ablaufkonfiguration mit einem XML-Beispiel darstellen. In den Inline-Kommentaren finden Sie Informationen zu jedem Ablauf. Dies ist ein Beispiel – die Namen von Abläufen und Pfaden können beliebig konfiguriert werden. Unter OAuth-Endpunkte und -Richtlinien konfigurieren finden Sie eine kurze Übersicht über die Schritte zum Erstellen eines benutzerdefinierten Ablaufs wie diesem.

Siehe auch die Beispielimplementierung auf GitHub.

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <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>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

Abläufe mit Richtlinien konfigurieren

Jedem Endpunkt ist eine Richtlinie zugeordnet. Sehen wir uns Beispiele der Richtlinien an. Unter OAuth-Endpunkte und -Richtlinien konfigurieren finden Sie eine kurze Übersicht über die erforderlichen Schritte zum Hinzufügen von OAuthV2-Richtlinien zu Proxy-Endpunkten.

Anmeldeweiterleitung

Dies ist der Pfad /oauth/authorize. Die angehängte Richtlinie ist für die Weiterleitung des Nutzers zu einer Anmeldeanwendung verantwortlich, bei der der Endnutzer die Clientanwendung sicher authentifizieren und autorisieren kann, auf ihre geschützten Ressourcen zuzugreifen, ohne dass Nutzername und Passwort der Clientanwendung zugeordnet werden müssen. Sie können dies mit einer Service-Callout-Richtlinie, JavaScript oder anderen Mitteln erreichen.

Der API-Aufruf für die Anfrage ist eine GET-Anfrage und benötigt die Abfrageparameter "client_id", "response_type", "redirect_uri", "scope" und "state".

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

Best Practice: Die Anmeldeanwendung sendet in der Regel eine Weiterleitungsantwort an Apigee. Apigee leitet den Browser des Nutzers dann an die registrierte Callback-URL weiter. Es wird empfohlen, die Antwort nicht direkt an den User-Agent/Client zu senden, um die Offenlegung vertraulicher Informationen zu verhindern. Die Callback-URL wird beim Registrieren einer App im Entwicklerportal oder mit der Developer Apps API

definiert.

Authentifizierungscode abrufen

Dies ist der Pfad /oauth/authorizationcode. Er verwendet die OAuthV2-Richtlinie mit dem angegebenen GenerateAuthorizationCode-Vorgang.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

Der API-Aufruf zum Abrufen des Autorisierungscodes ist ein GET-Vorgang und erfordert die Abfrageparameter "client_id", "response_type" sowie optional den Bereich und den Status, wie in diesem Beispiel gezeigt:

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

Zugriffstoken abrufen

Diese Richtlinie wird an den Pfad /oauth/accesstoken angehängt. Sie verwendet die OAuthV2-Richtlinie mit dem angegebenen GenerateAccessCode-Vorgang. In diesem Fall wird der Parameter "grant_type" als Abfrageparameter erwartet:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn>
    <SupportedGrantTypes>
        <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

Der API-Aufruf zum Abrufen des Zugriffscodes ist ein POST und muss die Client-ID, client_secret, grant_type=authorization_code und optional den Bereich enthalten. Beispiel:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Dies ist nur eine allgemeine Zusammenfassung. Ein Produktionsbeispiel enthält viele weitere Richtlinien für das Erstellen von URLs, für Transformationen und andere Aufgaben. Ein vollständiges, funktionsfähiges Projekt finden Sie im Beispiel auf GitHub.

Richtlinie zum Prüfen des Zugriffstokens anhängen

Hängen Sie an den Anfang jedes Ablaufs, der auf eine geschützte API zugreift, eine VerifyAccessToken-Richtlinie (OAuthV2-Richtlinie mit dem angegebenen VerifyAccessToken-Vorgang) an, damit sie ausgeführt wird, wenn eine Anfrage für eine geschützte Ressource eingeht. Apigee prüft, ob jede Anfrage ein gültiges Zugriffstoken hat. Andernfalls wird ein Fehler zurückgegeben. Die grundlegenden Schritte finden Sie unter Zugriffstoken überprü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>

Aufruf der geschützten API

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: Das Zugriffstoken wird auch als Inhabertoken bezeichnet.

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

Siehe auch Zugriffstoken senden.