Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen
OAuth hat sich als führendes Autorisierungsprotokoll für APIs entwickelt. Die Version von OAuth, die in diesem Thema ausführlich behandelt wird, ist in der OAuth 2.0-Spezifikation definiert.
OAuth ist ein Protokoll, mit dem App-Endnutzer Apps dazu autorisieren können, in ihrem Namen zu handeln. Dazu fordern sie Zugriffstokens von API-Anbietern an. Der API-Anbieter authentifiziert die Anmeldedaten des Endnutzers der Anwendung, stellt sicher, dass der Nutzer die Anwendung autorisiert hat, und stellt dann ein Zugriffstoken für die Anwendung aus. Wenn die Anwendung eine geschützte API nutzt, prüft Apigee Edge das Zugriffstoken, um sicherzustellen, dass es gültig und nicht abgelaufen ist. Als API-Anbieter müssen Sie Endpunkte bereitstellen, über die Anwendungen Zugriffstokens abrufen können.
Um Ihnen den Einstieg in die Verwendung von OAuth zu erleichtern, ermöglicht Ihnen Apigee Edge, OAuth mithilfe von Richtlinien zu konfigurieren und zu erzwingen, ohne dass Sie Code schreiben müssen. In diesem Thema erfahren Sie, wie Sie Ihre APIs schützen, Zugriffstokens abrufen und diese Zugriffstokens für den Zugriff auf geschützte APIs verwenden.
Die OAuth-Standardkonfiguration für Ihre Organisation
Der Einfachheit halber sind alle Organisationen auf Apigee Edge mit einer Reihe von OAuth 2.0-Endpunkten vorkonfiguriert, die den Berechtigungstyp für Clientanmeldedaten implementieren. Der Berechtigungstyp für Clientanmeldedaten definiert ein Verfahren für die Ausstellung von Zugriffstokens im Austausch gegen App-Anmeldedaten. Diese App-Anmeldedaten sind einfach das Consumer-Key-Secret-Paar, das Apigee Edge für jede in einer Organisation registrierte Anwendung ausstellt. „Clientanmeldedaten“ bezieht sich auf das Paar aus Consumer-Key und -Secret.
Weitere Informationen zum Ausstellen von Anmeldedaten für Apps mithilfe von Edge Developer Services finden Sie unter Apps registrieren und Schlüssel verwalten.
Aus diesem Grund ist es relativ einfach, das API-Sicherheitsschema von der API-Schlüsselvalidierung auf OAuth-Clientanmeldedaten zu erhöhen. Beide Schemas verwenden denselben Consumer-Key und dasselbe Secret, um die Client-App zu validieren. Der Unterschied besteht darin, dass Clientanmeldedaten eine zusätzliche Kontrollebene bieten, da Sie ein Zugriffstoken bei Bedarf einfach widerrufen können, ohne dass Sie den Consumer-Key der App widerrufen müssen. Wenn Sie mit den standardmäßigen OAuth-Endpunkten arbeiten möchten, können Sie einen beliebigen Consumer-Key und ein beliebiges Secret verwenden, die für die Anwendung in Ihrer Organisation generiert wurden, um Zugriffstokens vom Token-Endpunkt abzurufen. (Sie können Clientanmeldedaten sogar für Anwendungen aktivieren, die bereits Verbraucherschlüssel und -geheimnisse haben.)
Die vollständige Spezifikation für die Erteilung von Clientanmeldedaten finden Sie in der OAuth 2.0-Spezifikation.
API mit einer Richtlinie schützen
Bevor Sie Zugriffstokens verwenden können, müssen Sie Ihre APIs so konfigurieren, dass OAuth-Zugriffstokens zur Laufzeit validiert werden. Dazu konfigurieren Sie einen API-Proxy, der Zugriffstokens validate. Das bedeutet, dass jedes Mal, wenn eine Anwendung eine Anfrage zur Nutzung einer Ihrer APIs sendet, ein gültiges Zugriffstoken zusammen mit der API-Anfrage vorlegen muss. Apigee Edge bewältigt die Komplexität beim Generieren, Speichern und Validieren der bereitgestellten Zugriffstokens.
Sie können bei der Erstellung eines neuen API-Proxys ganz einfach eine OAuth-Überprüfung zu einer API hinzufügen. Wenn Sie einen neuen API-Proxy erstellen, können Sie Features hinzufügen. Wie unten gezeigt, können Sie eine Bestätigung von OAuth 2.0-Zugriffstokens hinzufügen, indem Sie das Optionsfeld neben Secure with OAuth v2.0 Access Tokens (Sicher mit OAuth v2.0-Zugriffstokens) auswählen. Wenn Sie diese Option auswählen, werden zwei Richtlinien an den neu erstellten API-Proxy angehängt: eine zum Überprüfen von Zugriffstokens und eine zum Entfernen des Zugriffstokens nach der Bestätigung.
Wenn Sie die Option Secure with OAuth v2.0 Access Tokens (Mit OAuth v2.0-Zugriffstokens sichern) auswählen, wird außerdem das Kästchen Publish API Product (API-Produkt veröffentlichen) aktiviert. Aktivieren Sie diese Option, wenn beim Erstellen des neuen API-Proxys automatisch ein Produkt generiert werden soll. Das automatisch generierte Produkt wird mit einer Verknüpfung mit dem neuen API-Proxy erstellt. Wenn Sie diese neue API mit einem bereits vorhandenen Produkt verknüpfen möchten, müssen Sie dieses Kästchen deaktivieren, damit Sie kein unnötiges Produkt erstellen. Informationen zu Produkten finden Sie unter Was ist ein API-Produkt?
Wenn Sie die Zugriffstoken-Überprüfung für einen bereits vorhandenen API-Proxy aktivieren müssen, müssen Sie lediglich eine Richtlinie vom Typ OAuthV2 an die zu schützende API anhängen. Für OAuthV2-Richtlinien wird ein Vorgang festgelegt. Wenn Sie Zugriffstokens validieren möchten, geben Sie den Vorgang namens VerifyAccessToken an. Andere Arten von Vorgängen, die vom OAuthV2-Richtlinientyp unterstützt werden, sind GenerateAccessToken und GenerateRefreshToken. Sie erfahren mehr über diese Vorgänge beim Einrichten von OAuth-Endpunkten.)
VerifyOAuthTokens-Richtlinie vom Typ OAuthV2
Hier sehen Sie eine Beispielrichtlinie zum Validieren von Zugriffstokens. Die Einstellungen werden in der folgenden Tabelle erläutert.
<OAuthV2 name="VerifyOAuthTokens"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
Richtlinieneinstellungen
| Name | Beschreibung | Standard | Erforderlich? |
|---|---|---|---|
OAuthV2 |
Der Richtlinientyp | ||
name |
Der Name der Richtlinie, auf den in der Konfiguration des API-Proxy-Endpunkts verwiesen wird. | – | Ja |
Operation |
Der Vorgang, der von der OAuthV2-Richtlinie ausgeführt werden soll. Durch Angabe von „VerifyAccessToken“ konfigurieren Sie die Richtlinie so, dass Anfragen nach Zugriffstokens geprüft werden. Außerdem wird bestätigt, dass das Zugriffstoken gültig, nicht abgelaufen und für die Nutzung der angeforderten API-Ressource (URI) genehmigt ist. Um diese Prüfung durchzuführen, liest die Richtlinie das API-Produkt vor, das die App nutzen darf. | – | Ja |
Rufen Sie zum Erstellen dieser Richtlinie in der Verwaltungsoberfläche APIs > API-Proxys auf.
Wählen Sie aus der Liste der API-Proxys weatherapi aus.
Wählen Sie in der Übersicht für weatherapi die Ansicht Develop (Entwickeln) aus.
Wählen Sie im Drop-down-Menü Neue Richtlinie > OAuth v2.0 aus.
Nachdem Sie die OAuth v2.0-Richtlinie ausgewählt haben, wird das Konfigurationsmenü Neue Richtlinie angezeigt.
Geben Sie Ihrer Richtlinie einen beschreibenden Namen und wählen Sie Attach Policy (Richtlinie anhängen), Flow PreFlow (Ablauf PreFlow) und Request (Anfrage) als Einstellungen zum Anhängen von Richtlinien aus.
Wählen Sie Add (Hinzufügen) aus. Die Richtlinie wird erstellt und an die PreFlow-Anfrage der weatherapi angehängt.
Nachdem Sie die Richtlinie hinzugefügt haben, wird die folgende PreFlow-Anfrage im Bereich Designer angezeigt.
Wenn Sie lokal in einem Texteditor oder einer IDE arbeiten, hängen Sie die Richtlinie an den PreFlow der Anfrage des API-Proxys an, den Sie schützen möchten:
<PreFlow>
<Request>
<Step><Name>VerifyOAuthTokens</Name></Step>
</Request>
</PreFlow>
Durch das Anhängen der Richtlinie an den PreFlow der Anfrage stellen Sie sicher, dass die Richtlinie immer für alle Anfragenachrichten erzwungen wird.
Du hast jetzt eine API mit OAuth 2.0-Clientanmeldedaten gesichert. Im nächsten Schritt erfahren Sie, wie Sie ein Zugriffstoken abrufen und damit auf die sichere API zugreifen.
Zugriffstoken für den Zugriff auf eine geschützte Ressource verwenden
Da die Weatherapi jetzt mit OAuth 2.0 gesichert ist, müssen Apps Zugriffstokens für die Nutzung der API bereitstellen. Für den Zugriff auf eine geschützte Ressource stellt die Anwendung in der Anfrage ein Zugriffstoken als "Authorization"-HTTP-Header wie folgt dar:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
Da an die API eine OAuthV2-Richtlinie angehängt ist, prüft Apigee Edge, ob das angegebene Zugriffstoken gültig ist, gewährt dann Zugriff auf die API und gibt den Wetterbericht an die Anwendung zurück, die die Anfrage gestellt hat.
Aber wie erhalten Apps Zugriffstokens? Damit beschäftigen wir uns im nächsten Abschnitt.
Clientanmeldedaten gegen ein Zugriffstoken austauschen
Anwendungen erhalten Zugriffstokens, indem sie ihre Consumer-Key-Secret-Paare an den Token-Endpunkt senden. Der Tokenendpunkt wird im API-Proxy als oauth konfiguriert. Daher müssen Anwendungen die vom oauth-API-Proxy ausgegebene API aufrufen, um ein Zugriffstoken zu erhalten. Nachdem die App ein Zugriffstoken hat, kann sie die Weatherapi wiederholt aufrufen, bis das Zugriffstoken abläuft oder das Zugriffstoken widerrufen wird.
Jetzt müssen Sie sich selbst als App-Entwickler bezeichnen. Sie möchten die weatherapi aufrufen, also benötigen Sie ein Zugriffstoken für Ihre Anwendung. Als Erstes müssen Sie ein Consumer-Key-Secret-Paar abrufen (auch als API-Schlüssel oder App-Schlüssel bezeichnet).
Sie können einen Consumer-Key und ein Consumer-Secret erhalten, indem Sie eine Anwendung in Ihrer Organisation in Apigee Edge registrieren.
Sie können alle Apps in Ihrer Organisation in der Verwaltungs-UI von Apigee Edge ansehen.
Die Liste der Apps, die in Ihrer Organisation registriert sind, wird angezeigt.
(Wenn keine Apps angezeigt werden, können Sie unter Apps registrieren und API-Schlüssel verwalten nachlesen, wie Sie eine App registrieren.)
Wählen Sie eine App aus der Liste aus, um das detaillierte Profil aufzurufen.
Notieren Sie sich in der Detailansicht der ausgewählten App die Felder für Consumer Key (Consumer-Key) und Consumer Secret (Consumer-Secret). Diese beiden Werte sind die Clientanmeldedaten, mit denen Sie ein OAuth-Zugriffstoken abrufen.
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass
Dieser Aufruf gibt eine Liste der Anwendungen nach App-ID zurück.
[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]
Sie können das Profil einer App durch einen einfachen GET-Aufruf mit der App-ID abrufen:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass
Beispiel:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass
Der API-Aufruf gibt das Profil der von Ihnen angegebenen App zurück. Ein Anwendungsprofil für weatherapp hat beispielsweise die folgende JSON-Darstellung:
{
"accessType" : "read",
"apiProducts" : [ ],
"appFamily" : "default",
"appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
"attributes" : [ ],
"callbackUrl" : "http://weatherapp.com",
"createdAt" : 1380290158713,
"createdBy" : "noreply_admin@apigee.com",
"credentials" : [ {
"apiProducts" : [ {
"apiproduct" : "PremiumWeatherAPI",
"status" : "approved"
} ],
"attributes" : [ ],
"consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"consumerSecret" : "hAr4Gn0gA9vAyvI4",
"expiresAt" : -1,
"issuedAt" : 1380290161417,
"scopes" : [ ],
"status" : "approved"
} ],
"developerId" : "5w95xGkpnjzJDBT4",
"lastModifiedAt" : 1380290158713,
"lastModifiedBy" : "noreply_admin@apigee.com",
"name" : "weatherapp",
"scopes" : [ ],
"status" : "approved"
}
Notieren Sie sich die Werte für consumerKey und consumerSecret. Sie verwenden diese Anmeldedaten, um ein Zugriffstoken zu erhalten, indem Sie sie als Anmeldedaten für die Basisauthentifizierung in einer HTTP-Anfrage vorlegen, wie unten dargestellt. Der Berechtigungstyp wird der Anfrage als Abfrageparameter angezeigt.
(Achten Sie darauf, den Wert der Variablen {org_name} so zu ändern, dass sie den Namen Ihrer Organisation in Apigee Edge widerspiegelt.)
Anfrage zum Abrufen eines Zugriffstokens erstellen
Ersetzen Sie in der folgenden Anfrage den Wert von consumerKey durch client_id. Ersetzen Sie client_secret durch den Wert des zugehörigen consumerSecret.
$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'
API-Dienste überprüfen den Consumer-Schlüssel und das Secret und generieren dann eine Antwort, die das Zugriffstoken für diese Anwendung enthält:
{
"issued_at" : "1380892555397",
"application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
"scope" : "",
"status" : "approved",
"api_product_list" : "[oauth-test]",
"expires_in" : "3599",
"developer.email" : "tesla@weathersample.com",
"organization_id" : "0",
"client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
"organization_name" : "rqa",
"refresh_token_expires_in" : "0",
"refresh_count" : "0"
}
Notieren Sie sich den access_token-Wert aus der obigen Antwort. Dies ist das Zugriffstoken, mit dem die Anwendung Laufzeitzugriff auf geschützte Ressourcen erhält. Das Zugriffstoken für diese Anwendung ist ylSkZIjbdWybfs4fUQe9BqP0LH5Z.
Sie haben jetzt das gültige Zugriffstoken ylSkZIjbdWybfs4fUQe9BqP0LH5Z, mit dem Sie auf geschützte APIs zugreifen können.
Mit der OAuth-Standardkonfiguration arbeiten
Jede Organisation (auch eine kostenlose Testorganisation) auf Apigee Edge wird mit einem OAuth-Token-Endpunkt bereitgestellt. Der Endpunkt ist im API-Proxy mit Richtlinien mit dem Namen oauth vorkonfiguriert. Sie können den Tokenendpunkt verwenden, sobald Sie ein Konto in Apigee Edge erstellen.
Der standardmäßige OAuth-Endpunkt stellt den folgenden Endpunkt-URI bereit:
/oauth/client_credential/accesstoken
Veröffentlichen Sie diesen URI für Entwickler, die Zugriffstokens anfordern müssen. App-Entwickler konfigurieren ihre Apps so, dass dieser Endpunkt aufgerufen wird. Dabei präsentieren sie ihre Consumer-Key- und -Secret-Paare, um Zugriffstokens zu erhalten.
Der Standard-Token-Endpunkt der Clientanmeldedaten wird über das Netzwerk unter der folgenden URL bereitgestellt:
https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken
Wenn der Name Ihrer Organisation beispielsweise "apimakers" ist, lautet die URL:
https://apimakers-test.apigee.net/oauth/client_credential/accesstoken
Dies ist die URL, die Entwickler aufrufen, um Zugriffstokens zu erhalten.
Dreibeinige OAuth-Konfigurationen
Bei dreibeinigen OAuth-Konfigurationen (Autorisierungscode, implizite und Passwortzuweisung) müssen Sie als API-Anbieter Anwendungs-Endnutzer authentifizieren. Da jede Organisation Nutzer auf unterschiedliche Weise authentifiziert, ist eine gewisse Richtlinienanpassung oder ein gewisser Code erforderlich, um OAuth in Ihren Nutzerspeicher einzubinden. Beispielsweise können alle Ihre Nutzer in Active Directory, in einem LDAP oder in einem anderen Nutzerspeicher gespeichert sein. Um dreibeiniges OAuth auszuführen, müssen Sie eine Prüfung dieses Nutzerspeichers in den gesamten OAuth-Ablauf integrieren.
OAuth 1.0a
Weitere Informationen zur OAuth 1.0a-Richtlinie finden Sie im Hilfeartikel OAuth 1.0a-Richtlinie.
Hilfe aufrufen
Weitere Informationen erhalten Sie unter Apigee-Kundensupport.