Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen
In diesem Thema wird erläutert, wie OAuth 2.0-Bereiche in Apigee Edge verwendet werden.
Was ist ein OAuth2-Bereich?
OAuth 2.0-Bereiche bieten die Möglichkeit, den Umfang des Zugriffs zu beschränken, der einem Zugriffstoken gewährt wird. Beispiel: Ein Zugriffstoken, das an eine Clientanwendung ausgegeben wird, kann READ- und WRITE-Zugriff auf geschützte Ressourcen oder nur READ-Zugriff gewähren. Sie können APIs implementieren, um alle Bereiche oder Kombinationen aus Bereichen zu erzwingen. Wenn dann ein Client ein Token mit dem READ-Bereich erhält und versucht, einen API-Endpunkt aufzurufen, für den WRITE-Zugriff erforderlich ist, schlägt der Aufruf fehl.
In diesem Thema wird erläutert, wie Bereiche Zugriffstokens zugewiesen werden und wie Apigee Edge OAuth 2.0-Bereiche erzwingt. Nachdem Sie dieses Thema gelesen haben, können Sie Bereiche mit Zuversicht verwenden.
Wie werden Bereiche zu Zugriffstokens zugewiesen?
Wenn Edge ein Zugriffstoken generiert, kann es diesem Token einen Bereich zuweisen. Damit Sie verstehen, wie dies geschieht, müssen Sie sich zuerst mit den folgenden Apigee Edge-Entitäten vertraut machen: API-Produkte, Entwickler und Entwickleranwendungen. Eine Einführung finden Sie unter Einführung in die Veröffentlichung. Wir empfehlen, dieses Material zu lesen, bevor Sie fortfahren.
Ein Zugriffstoken ist ein langer String mit zufällig dargestellten Zeichen, anhand dessen Edge eingehende API-Anfragen verifizieren kann. Betrachten Sie das Token als eine Art Ersatz für Anmeldedaten, die aus einem typischen Nutzernamen und einem Passwort bestehen. Technisch gesehen ist das Token ein Schlüssel, der sich auf eine Sammlung von Metadaten bezieht, die in etwa so aussehen:
{
"issued_at" : "1416962591727",
"application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
"scope" : "A",
"status" : "approved",
"api_product_list" : "[scopecheck1-bs0cSuqS9y]",
"expires_in" : "1799", //--in seconds
"developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
"organization_id" : "0",
"token_type" : "BearerToken",
"client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
"access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
"organization_name" : "wwitman",
"refresh_token_expires_in" : "0", //--in seconds
"refresh_count" : "0"
}
Die Metadaten des Tokens enthalten den String des tatsächlichen Zugriffstokens, Ablaufinformationen, die Identifizierung der Entwickleranwendung, des Entwicklers und der mit dem Token verknüpften Produkte. Die Metadaten enthalten auch einen "Bereich".
Wie erhält das Token seinen Bereich?
Als Erstes müssen Sie beachten, dass jedem Produkt in einer Entwickleranwendung null oder mehr Bereiche zugewiesen werden können. Diese Bereiche können zugewiesen werden, wenn das Produkt erstellt wird, oder sie können später hinzugefügt werden. Die Bereiche sind als Liste mit Namen in den Metadaten des jeweiligen Produkts enthalten.
Wenn Sie eine Entwickler-App erstellen und Produkte hinzufügen, prüft Edge alle Produkte in der Entwickler-App und erstellt eine Liste aller Bereiche für diese Produkte (die Master- oder globale Bereichsliste der Anwendung – eine Vereinigung aller erkannten Bereiche).
.Wenn eine Client-App ein Zugriffstoken von Apigee Edge anfordert, kann sie optional angeben, welche Bereiche mit diesem Token verknüpft werden sollen. Die folgende Anfrage fordert beispielsweise den Bereich "A" an. Das heißt, der Client fordert den Autorisierungsserver (Edge) auf, ein Zugriffstoken mit Bereich A zu generieren. Dadurch erhält die Anwendung die Autorisierung, APIs im Bereich A aufzurufen. Die Anwendung sendet eine POST-Anfrage wie diese:
curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A
Was passiert dann?
Wenn Edge diese Anfrage erhält, weiß es, welche Anwendung die Anfrage durchführt, und auch, welche Entwickleranwendung der Client registriert hat. Die Client-ID und der Clientschlüssel werden im grundlegenden Authentifizierungsheader codiert. Da der Abfrageparameter scope enthalten ist, muss Edge entscheiden, ob eines der mit der Entwickleranwendung verknüpften API-Produkte den Bereich "A" hat. In diesem Fall wird ein Zugriffstoken mit dem Bereich "A" generiert. Eine weitere Möglichkeit, dies zu betrachten, ist der Suchparameter des Bereichs als eine Art Filter. Wenn die Entwickleranwendung die Bereiche "A, B, X" erkennt und der Suchparameter "scope=X Y Z" angibt, wird dem Token nur der Bereich "X" zugewiesen.
Was geschieht, wenn der Client keinen Bereichsparameter anhängt? In diesem Fall generiert Edge ein Token, das alle Bereiche enthält, die von der Entwickler-App erkannt wurden. Es ist wichtig zu verstehen, dass das Standardverhalten darin besteht, ein Zugriffstoken zurückzugeben, das die Gesamtheit aller Bereiche für alle Produkte in der Entwickler-App enthält.
Wenn keines der mit einer Entwickler-App verknüpften Produkte Bereiche angibt und ein Token einen Bereich hat, schlagen Aufrufe mit diesem Token fehl.
Nehmen wir an, eine Entwickler-App erkennt diese Bereiche: A B C D. Dies ist die Masterliste der Bereiche für die Anwendung. Beispiel: Ein Produkt in der Anwendung hat die Bereiche A und B und ein zweites die Bereiche C und D oder eine beliebige Kombination. Wenn der Client den Parameter scope nicht angibt oder wenn er den Bereichsparameter ohne Wert angibt, werden dem Token alle vier Bereiche zugewiesen: A, B, C und D. Auch das Token erhält eine Reihe von Bereichen, die die Vereinigung aller Bereiche darstellt, die von der Entwickler-App erkannt werden.
Es gibt noch einen weiteren Fall, bei dem das Standardverhalten darin besteht, ein Zugriffstoken mit allen erkannten Bereichen zurückzugeben. In diesem Fall gibt die Richtlinie "GenerateAccessToken" (die Apigee Edge-Richtlinie, die Zugriffstokens generiert) kein <Scope>-Element angibt.
In der folgenden GenerateAccessToken-Richtlinie beispielsweise ist <Scope> angegeben. Wenn dieses <Scope>-Element fehlt oder vorhanden, aber leer ist, wird das Standardverhalten ausgeführt.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
<DisplayName>OAuthV2 - Generate Access Token</DisplayName>
<Attributes>
<Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
</Attributes>
<Scope>request.queryparam.scope</Scope>
<GrantType>request.formparam.grant_type</GrantType>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>GenerateAccessToken</Operation>
<SupportedGrantTypes>
<GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
<GenerateResponse enabled="true"/>
</OAuthV2>
Wie werden Bereiche erzwungen?
Denken Sie zuerst daran, dass Zugriffstokens in Apigee Edge mit der OAuthV2-Richtlinie validiert werden, die in der Regel am Anfang eines Proxy-Ablaufs platziert wird. Für die Richtlinie muss der Vorgang „VerifyAccessToken“ angegeben sein. Sehen Sie sich diese Richtlinie an:
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
<GenerateResponse enabled="true"/>
</OAuthV2>
Beachten Sie das <Scope>-Element. Damit wird angegeben, welche Bereiche die Richtlinie akzeptiert.
In diesem Beispiel ist die Richtlinie nur erfolgreich, wenn das Zugriffstoken den Bereich "A" enthält. Wenn dieses <Scope>-Element weggelassen wird oder keinen Wert hat, ignoriert die Richtlinie den Bereich des Zugriffstokens.
Jetzt haben Sie die Möglichkeit, Zugriffstokens auf der Grundlage von Bereichen zu validieren und können Ihre APIs so entwerfen, dass bestimmte Bereiche erzwungen werden. Dazu entwerfen Sie benutzerdefinierte Abläufe und hängen bereichssensitive VerifyAccessToken-Richtlinien daran an.
Nehmen wir an, dass in der API ein Ablauf für den Endpunkt /resourceA definiert ist:
<Flow name="resourceA">
<Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
<Description>Get a resource A</Description>
<Request>
<Step>
<Name>OAuthV2-VerifyAccessTokenA</Name>
</Step>
</Request>
<Response>
<Step>
<Name>AssignMessage-CreateResponse</Name>
</Step>
</Response>
</Flow>
Wenn dieser Ablauf ausgelöst wird (eine Anfrage enthält /resourceA im Pfadsuffix), wird die OAuthV2-VerifyAccessTokenA-Richtlinie sofort aufgerufen. Diese Richtlinie prüft, ob das Zugriffstoken gültig ist und ermittelt, welche Bereiche das Token unterstützt. Wenn die Richtlinie wie im folgenden Beispiel konfiguriert ist, mit <Scope>A</Scope>, funktioniert die Richtlinie nur dann erfolgreich, wenn das Zugriffstoken den Bereich "A" hat. Andernfalls wird ein Fehler zurückgegeben.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>
Zusammenfassend lässt sich sagen, dass API-Entwickler verantwortlich sind für die Integration der Erzwingung von Bereichen in ihre APIs. Dazu werden benutzerdefinierte Abläufe für die Verarbeitung bestimmter Bereiche erstellt und VerifyAccessToken-Richtlinien angehängt, um diese Bereiche zu erzwingen.
Codebeispiele
Betrachten wir nun einige Beispiele für API-Aufrufe. Anhand dieser Beispiele wird veranschaulicht, wie Tokens Bereiche erhalten und wie Bereiche erzwungen werden.
Standardfall
Angenommen, Sie haben eine Entwickler-App mit Produkten und der Inhalt der Produktbereiche lautet: A, B und C. Dieser API-Aufruf fordert ein Zugriffstoken an, gibt jedoch keinen Bereichsabfrageparameter an.
curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials
In diesem Fall erhält das generierte Token die Bereiche A, B und C (Standardverhalten). Die Metadaten des Tokens sehen in etwa so aus:
{
"issued_at" : "1417016208588",
"application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
"scope" : "A B C",
"status" : "approved",
"api_product_list" : "[scopecheck1-yEgQbQqjRR]",
"expires_in" : "1799", //--in seconds
"developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
"organization_id" : "0",
"token_type" : "BearerToken",
"client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
"access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
"organization_name" : "wwitman",
"refresh_token_expires_in" : "0", //--in seconds
"refresh_count" : "0"
}
Angenommen, Sie haben einen API-Endpunkt mit dem Bereich „A“ (d. h. das zugehörige VerifyAccessToken erfordert den Bereich „A“). Hier ist die Richtlinie „VerifyAccessToken“:
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>
Hier sehen Sie einen Beispielaufruf und einen Endpunkt, der den Bereich A erzwingt:
curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA
Dieser GET-Aufruf ist erfolgreich:
{
"hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
}
Er ist erfolgreich, da die VerifyAccessToken-Richtlinie, die ausgelöst wird, wenn der Endpunkt aufgerufen wird, den Bereich A erfordert und dem Zugriffstoken die Bereiche A, B und C zugewiesen wurden – das Standardverhalten.
Fall mit Filterung
Angenommen, Sie haben eine Entwickler-App mit Produkten, die die Bereiche A, B, C und X haben. Sie fordern ein Zugriffstoken an und fügen den Abfrageparameter scope ein und zwar so:
curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'
In diesem Fall erhält das generierte Token die Bereiche A und X, da sowohl A als auch X gültige Bereiche sind. Denken Sie daran, dass die Entwickleranwendung die Bereiche A, B, C und X erkennt. In diesem Fall filtern Sie die Liste der API-Produkte anhand dieser Bereiche. Wenn ein Produkt den Bereich A oder X hat, können Sie API-Endpunkte konfigurieren, die diese Bereiche erzwingen. Wenn ein Produkt nicht den Bereich A oder X hat, z. B. B, C und Z, können die APIs, die die Bereiche A oder X erzwingen, nicht mit dem Token aufgerufen werden.
Folgendes passiert, wenn Sie die API mit dem neuen Token aufrufen:
curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX
Das Zugriffstoken wird vom API-Proxy validiert. Beispiel:
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A X</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>
Die GET-Aufruf-Trigger sind erfolgreich und es gibt eine Antwort zurück. Beispiel:
{
"hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
}
Das ist erfolgreich, da die VerifyAccessToken-Richtlinie einen Bereich A oder X erfordert, und das Zugriffstoken einen Bereich A und X enthält. Wenn das Element <Scope> auf "B" gesetzt wäre, würde der Aufruf fehlschlagen.
Zusammenfassung
Es ist wichtig zu verstehen, wie Apigee Edge OAuth 2.0-Bereiche verarbeitet. Hier einige wichtige Punkte:
- Eine Entwickleranwendung "erkennt" die Vereinigung aller Bereiche, die für alle ihre Produkte definiert sind.
- Wenn eine Anwendung ein Zugriffstoken anfordert, können Sie festlegen, welche Bereiche sie haben sollen. Es ist Aufgabe von Apigee Edge (des Autorisierungsservers) herauszufinden, welche Bereiche dem Zugriffstoken tatsächlich (a) anhand der angeforderten Bereiche und (b) anhand der von der Entwickleranwendung erkannten Bereiche zugewiesen werden.
- Wenn Apigee Edge nicht für die Überprüfung des Bereichs konfiguriert ist (das Element
<Scope>fehlt in der Richtlinie "VerifyAccessToken" oder ist es leer), ist der API-Aufruf erfolgreich, solange der Bereich, der in das Zugriffstoken eingebettet ist, mit einem der Bereiche übereinstimmt, die von der registrierten Entwickleranwendung erkannt werden (einer der Bereiche in der "Master"liste der Bereiche der Anwendung). - Wenn mit einem Zugriffstoken keine Bereiche verknüpft sind, gilt das nur für Fälle, in denen Edge den Bereich nicht berücksichtigt (das
<Scope>-Element fehlt in der Richtlinie "VerifyAccessToken" oder ist leer).