Zugriffstoken und Autorisierungscodes anfordern

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

In diesem Thema erfahren Sie, wie Sie Zugriffstokens und Autorisierungscodes anfordern, OAuth 2.0-Endpunkte konfigurieren und Richtlinien für jeden unterstützten Berechtigungstyp konfigurieren.

Beispielcode

Die in diesem Thema beschriebenen Richtlinien und Endpunkte sind auf GitHub im Projekt oauth-doc-examples im Apigee api-platform-samples-Repository verfügbar. Sie können den Beispielcode bereitstellen und die in diesem Thema gezeigten Beispielanfragen testen. Weitere Informationen finden Sie in der README-Datei des Projekts.

Anfordern eines Zugriffstoken: Grant-Typ "Autorisierungscode"

In diesem Abschnitt wird erläutert, wie Sie ein Zugriffstoken mithilfe des Ablaufs für den Grant-Typ "Autorisierungscode" anfordern. Eine Einführung in die OAuth 2.0-Grant-Typen finden Sie unter Einführung in OAuth 2.0.

Beispielanfrage

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Erforderliche Parameter

Standardmäßig müssen diese Parameter x-www-form-urlencoded sein und im Anfragetext angegeben werden (wie im Beispiel oben gezeigt). Sie können die Standardeinstellung jedoch ändern, indem Sie die Elemente <GrantType>, <Code> und <RedirectUri> in der OAuthV2-Richtlinie konfigurieren, die mit diesem /accesstoken-Endpunkt verknüpft ist. Weitere Informationen finden sich unter OAuthV2-Richtlinie.

  • grant_type – Muss auf den Wert authorization_code festgelegt sein.
  • code – Der Autorisierungscode, der vom Endpunkt /authorize (oder wie immer Sie diesen benannt haben) erfasst wurde. Wenn Sie ein Zugriffstoken mit dem Ablauf für den Grant-Typ "Autorisierungscode" anfordern möchten, müssen Sie zuerst einen Autorisierungscode abrufen. Weitere Informationen finden sich unten im Abschnitt Autorisierungscodes anfordern. Weitere Informationen finden sich unter Grant-Typ "Autorisierungscode" implementieren.
  • redirect_uri: Dieser Parameter muss angegeben werden, falls der Parameter redirect_uri in der vorherigen Autorisierungscodeanfrage enthalten war. Wenn der Parameter redirect_uri nicht in der Autorisierungscodeanfrage enthalten war und Sie diesen Parameter nicht angeben, verwendet die Richtlinie den Wert der Callback-URL, die bei der Registrierung der Entwickler-App bereitgestellt wurde.

Optionale Parameter

  • state – Ein String, der mit der Antwort zurückgegeben wird. Wird in der Regel verwendet, um eine websiteübergreifende Anfragefälschung zu verhindern.
  • scope – Ermöglicht das Filtern der Liste der API-Produkte, mit denen das erstellte Token verwendet werden kann. Ausführliche Informationen zu Bereichen finden sich unter Mit OAuth2-Bereichen arbeiten.

Authentifizierung

Sie müssen Client-ID und Clientschlüssel entweder als Basis-Authentifizierungsheader (Base64-codiert) oder als Formularparameter client_id und client_secret übergeben. Sie erhalten diese Werte von einer registrierten Entwickler-App. Siehe auch "Basis-Anmeldedaten für die Authentifizierung codieren".

Beispielendpunkt

Dies ist ein Beispiel für die Endpunktkonfiguration zum Generieren eines Zugriffstoken. Es führt die Richtlinie "GenerateAccessToken" aus, die zur Unterstützung des Grant-Typs "authorization_code" konfiguriert sein muss.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Beispielrichtlinie

Dies ist eine grundlegende "GenerateAccessToken"-Richtlinie, die für die Annahme des Grant-Typs authorization_code konfiguriert ist. Informationen zu optionalen Konfigurationselementen, die mit dieser Richtlinie konfiguriert werden können, finden sich unter OAuthV2-Richtlinie.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Rückgabe

Ist <GenerateResponse> aktiviert, so gibt die Richtlinie eine JSON-Antwort zurück, die das Zugriffstoken enthält, wie unten dargestellt. Der Grant-Typ authorization_code erstellt ein Zugriffs- und ein Aktualisierungstoken, sodass eine Antwort so aussehen kann:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Ist <GenerateResponse> auf "false" gesetzt, gibt die Richtlinie keine Antwort zurück. Stattdessen wird der folgende Satz Ablaufvariablen mit Daten gefüllt, die sich auf die Zugriffstoken-Erteilung beziehen.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Beispiel:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Anfordern eines Zugriffstoken: Grant-Typ "Client-Anmeldedaten"

In diesem Abschnitt wird erläutert, wie Sie Zugriffstoken mit dem Ablauf für den Grant-Typ "Client-Anmeldedaten" anfordern. Eine Einführung in die OAuth 2.0-Grant-Typen finden Sie unter Einführung in OAuth 2.0.

Beispielanfrage

Informationen zur Codierung des Basisauthentifizierungsheaders im folgenden Aufruf finden Sie unter Anmeldedaten für die Basisauthentifizierung codieren. 

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

Erforderliche Parameter

Der erforderliche Parameter „grant_type“ muss x-www-form-urlencoded sein und im Anfragetext angegeben sein (wie im Beispiel oben gezeigt). Sie können diese Standardeinstellung jedoch ändern, indem Sie das Element <GrantType> in der OAuthV2-Richtlinie konfigurieren, die an diesen /accesstoken-Endpunkt angehängt ist. Sie können beispielsweise den Parameter in einem Abfrageparameter übergeben. Weitere Informationen finden sich unter OAuthV2-Richtlinie.

  • grant_type – Muss auf den Wert client_credentials festgelegt sein.

Optionale Parameter

  • state – Ein String, der mit der Antwort zurückgegeben wird. Wird in der Regel verwendet, um eine websiteübergreifende Anfragefälschung zu verhindern.
  • scope – Ermöglicht das Filtern der Liste der API-Produkte, mit denen das erstellte Token verwendet werden kann. Ausführliche Informationen zu Bereichen finden sich unter Mit OAuth2-Bereichen arbeiten.

Authentifizierung

Sie müssen Client-ID und Clientschlüssel entweder als Basis-Authentifizierungsheader (Base64-codiert) oder als Formularparameter client_id und client_secret übergeben. Sie erhalten diese Werte von der mit der Anfrage verknüpften, registrierten Entwickler-App. Weitere Informationen finden Sie unter "Anmeldedaten für die Basisauthentifizierung codieren".

Beispielendpunkt

Dies ist ein Beispiel für die Endpunktkonfiguration zum Generieren eines Zugriffstoken. Es führt die Richtlinie "GenerateAccessToken" aus, die für die Unterstützung des Grant-Typs "client_credentials" konfiguriert sein muss.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Beispielrichtlinie

Dies ist eine grundlegende "GenerateAccessToken"-Richtlinie, die für die Annahme des Grant-Typs client_credentials konfiguriert ist. Informationen zu optionalen Konfigurationselementen, die mit dieser Richtlinie konfiguriert werden können, finden sich unter OAuthV2-Richtlinie.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Rückgabe

Ist <GenerateResponse> aktiviert, so gibt die Richtlinie eine JSON-Antwort zurück. Beachten Sie, dass Aktualisierungstokens mit dem Grant-Typ client_credentials nicht unterstützt werden. Es wird nur ein Zugriffstoken erstellt. Beispiel:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Ist <GenerateResponse> auf "false" gesetzt, gibt die Richtlinie keine Antwort zurück. Stattdessen wird der folgende Satz Ablaufvariablen mit Daten gefüllt, die sich auf die Zugriffstoken-Erteilung beziehen.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Beispiel:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Zugriffstoken anfordern: Grant-Typ "Passwort"

In diesem Abschnitt wird erläutert, wie Sie Zugriffstoken mit dem Grant-Typ "Anmeldedaten des Ressourceninhabers (Passwort)" anfordern. Eine Einführung in die OAuth 2.0-Grant-Typen finden Sie unter Einführung in OAuth 2.0.

Weitere Informationen zum Grant-Typ "Passwort", einschließlich eines vierminütigen Videos zur Implementierung, finden sich unter Implementierung des Grant-Typs "Passwort".

Beispielanfrage

Informationen zur Codierung des Basisauthentifizierungsheaders im folgenden Aufruf finden Sie unter Anmeldedaten für die Basisauthentifizierung codieren. 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

Erforderliche Parameter

Standardmäßig müssen diese Parameter x-www-form-urlencoded sein und im Anfragetext angegeben werden (wie im Beispiel oben gezeigt). Sie können die Standardeinstellung jedoch ändern, indem Sie die Elemente <GrantType>, <Username> und <Password> in der OAuthV2-Richtlinie konfigurieren, die mit diesem /token-Endpunkt verknüpft ist. Weitere Informationen finden sich unter OAuthV2-Richtlinie.

Nutzeranmeldedaten werden in der Regel auf Basis einer LDAP- oder JavaScript-Richtlinie unter Verwendung eines Anmeldedatenspeichers validiert.

  • grant_type – Muss auf den Wert password festgelegt sein.
  • username - Der Nutzername des Ressourceninhabers.
  • password – Das Passwort des Ressourceninhabers.

Optionale Parameter

  • state – Ein String, der mit der Antwort zurückgegeben wird. Wird in der Regel verwendet, um eine websiteübergreifende Anfragefälschung zu verhindern.
  • scope – Ermöglicht das Filtern der Liste der API-Produkte, mit denen das erstellte Token verwendet werden kann. Ausführliche Informationen zu Bereichen finden sich unter Mit OAuth2-Bereichen arbeiten.

Authentifizierung

Sie müssen Client-ID und Clientschlüssel entweder als Basis-Authentifizierungsheader (Base64-codiert) oder als Formularparameter client_id und client_secret übergeben. Sie erhalten diese Werte von der mit der Anfrage verknüpften, registrierten Entwickler-App. Weitere Informationen finden Sie unter "Anmeldedaten für die Basisauthentifizierung codieren".

Beispielendpunkt

Dies ist ein Beispiel für die Endpunktkonfiguration zum Generieren eines Zugriffstoken. Damit wird die Richtlinie "GenerateAccessToken" ausgeführt, die zur Unterstützung des Grant-Typs "Passwort" konfiguriert werden muss.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Beispielrichtlinie

Dies ist eine grundlegende "GenerateAccessToken"-Richtlinie, die für die Annahme des Grant-Typs "Passwort" konfiguriert ist. Informationen zu optionalen Konfigurationselementen, die mit dieser Richtlinie konfiguriert werden können, finden sich unter OAuthV2-Richtlinie.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Rückgabe

Ist <GenerateResponse> aktiviert, so gibt die Richtlinie eine JSON-Antwort zurück. Beachten Sie, dass beim Grant-Typ "Passwort" sowohl ein Zugriffs- als auch ein Aktualisierungstoken erstellt wird. Beispiel:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Ist <GenerateResponse> auf "false" gesetzt, gibt die Richtlinie keine Antwort zurück. Stattdessen wird der folgende Satz Ablaufvariablen mit Daten gefüllt, die sich auf die Zugriffstoken-Erteilung beziehen.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Beispiel:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Anfordern eines Zugriffstokens: Grant-Typ "Implizit"

In diesem Abschnitt wird erläutert, wie Sie ein Zugriffstoken mit dem Grant-Typ "Implizit" anfordern. Eine Einführung in die OAuth 2.0-Grant-Typen finden Sie unter Einführung in OAuth 2.0.

Beispielanfrage

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

Erforderliche Parameter

Standardmäßig müssen diese Parameter Abfrageparameter sein (siehe Beispiel oben). Sie können diese Standardeinstellung jedoch ändern, indem Sie die Elemente <ResponseType>, <ClientId> und <RedirectUri> in der OAuthV2-Richtlinie konfigurieren, die mit diesem /token-Endpunkt verknüpft ist. Weitere Informationen finden sich unter OAuthV2-Richtlinie.

Nutzeranmeldedaten werden in der Regel auf Basis einer LDAP-Dienst- oder JavaScript-Richtlinie unter Verwendung eines Anmeldedatenspeichers validiert.

  • response_type – Muss auf den Wert token festgelegt sein.
  • client_id – Die Client-ID einer registrierten Entwickler-App.
  • redirect_uri – Dieser Parameter ist obligatorisch, wenn bei der Registrierung der Client-Entwickler-App kein Callback-URI angegeben wurde. Wenn bei der Client-Registrierung eine Callback-URL angegeben wurde, wird sie mit diesem Wert verglichen und muss exakt mit diesem übereinstimmen.

Optionale Parameter

  • state – Ein String, der mit der Antwort zurückgegeben wird. Wird in der Regel verwendet, um eine websiteübergreifende Anfragefälschung zu verhindern.
  • scope – Ermöglicht das Filtern der Liste der API-Produkte, mit denen das erstellte Token verwendet werden kann. Ausführliche Informationen zu Bereichen finden sich unter Mit OAuth2-Bereichen arbeiten.

Authentifizierung

Für die implizite Zuweisung ist keine Basis- Authentifizierung erforderlich. Es ist aber erforderlich, eine Client-ID als Anfrageparameter zu übergeben, wie hier erläutert.

Beispielendpunkt

Dies ist ein Beispiel für die Endpunktkonfiguration zum Generieren eines Zugriffstoken. Dabei wird die Richtlinie "GenerateAccessTokenImplicitGrees" ausgeführt.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Beispielrichtlinie

Dies ist eine grundlegende GenerateAccessTokenImplicitGrant-Richtlinie, die Tokenanfragen für den impliziten Gewährungsvorgang verarbeitet. Informationen zu optionalen Konfigurationselementen, die mit dieser Richtlinie konfiguriert werden können, finden sich unter OAuthV2-Richtlinie.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Rückgabe

Ist <GenerateResponse> aktiviert, so gibt die Richtlinie eine 302-Standortweiterleitung im Antwortheader zurück. Die Weiterleitung verweist auf die im Parameter redirect_uri angegebene URL und wird mit dem Zugriffstoken und der Ablaufzeit des Token angehängt. Der Grant-Typ "Implizit" unterstützt Aktualisierungstokens nicht. Beispiel:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Ist <GenerateResponse> auf "false" gesetzt, gibt die Richtlinie keine Antwort zurück. Stattdessen wird der folgende Satz Ablaufvariablen mit Daten gefüllt, die sich auf die Zugriffstoken-Erteilung beziehen.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Beispiel:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Einen Autorisierungscode anfordern

Wenn Sie den Grant-Typ "Autorisierungscode" verwenden, müssen Sie einen Autorisierungscode anfordern, bevor Sie ein Zugriffstoken anfordern können.

Beispielanfrage

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

Dabei ist eine OAuthV2-GenerateAuthorizationCode-Richtlinie am Proxy-Endpunkt /oauth/authorize angehängt (siehe Beispielendpunkt unten).

Erforderliche Parameter

Standardmäßig müssen diese Parameter Abfrageparameter sein (siehe Beispiel oben). Sie können diese Standardeinstellung jedoch ändern, indem Sie die Elemente <ResponseType>, <ClientId> und <RedirectUri> in der OAuthV2-Richtlinie konfigurieren, die mit diesem /authorize-Endpunkt verknüpft ist. Weitere Informationen finden sich unter OAuthV2-Richtlinie.

  • response_type – Muss auf den Wert code festgelegt sein.
  • client_id – Die Client-ID einer registrierten Entwickler-App.

Optionale Parameter

  • redirect_uri – Wenn ein vollständiger Callback-URI in der registrierten Client-App angegeben wird, ist dieser Parameter optional. Andernfalls ist er erforderlich. Der Callback ist die URL, an die Edge den neu erstellten Autorisierungscode sendet. Siehe Anwendungen registrieren und API-Schlüssel verwalten.
  • state – Ein String, der mit der Antwort zurückgegeben wird. Wird in der Regel verwendet, um eine websiteübergreifende Anfragefälschung zu verhindern.
  • scope – Ermöglicht das Filtern der Liste der API-Produkte, mit denen das erstellte Token verwendet werden kann. Ausführliche Informationen zu Bereichen finden sich unter Mit OAuth2-Bereichen arbeiten.

Authentifizierung

Erfordert keine Basis-Authentifizierung, aber die Client-ID der registrierten Client-App muss in der Anfrage angegeben werden.

Beispielendpunkt

Hier ist ein Beispiel für eine Endpunktkonfiguration zum Generieren eines Autorisierungscodes:


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Beispielrichtlinie

Dies ist eine grundlegende GenerateAuthorizationCode-Richtlinie. Informationen zu optionalen Konfigurationselementen, die mit dieser Richtlinie konfiguriert werden können, finden sich unter OAuthV2-Richtlinie.

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Rückgabe

Ist <GenerateResponse> aktiviert, so gibt die Richtlinie den Abfrageparameter ?code an den Speicherort redirect_uri (Callback-URI) mit angehängtem Autorisierungscode zurück. Dies erfolgt über eine 302-Browser-Weiterleitung mit der URL im Standort-Header der Antwort. Beispiel: ?code=123456.

Ist <GenerateResponse> auf false gesetzt, so gibt die Richtlinie keine Antwort zurück. Stattdessen wird das folgende Set an Ablaufvariablen mit Daten zum Autorisierungscode gefüllt.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Beispiel:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Zugriffstokens aktualisieren

Aktualisierungstokens sind Anmeldedaten, mit denen Sie ein Zugriffstoken abrufen. Das ist in der Regel der Fall, wenn das Zugriffstoken abgelaufen ist oder ungültig wird. In der Antwort wird ein Aktualisierungstoken zurückgegeben, wenn Sie ein Zugriffstoken erhalten.

So fordern Sie mit einem Aktualisierungstoken ein neues Zugriffstoken an:

Beispielanfrage

Informationen zur Codierung des Basisauthentifizierungsheaders im folgenden Aufruf finden Sie unter Anmeldedaten für die Basisauthentifizierung codieren. 

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Erforderliche Parameter

  • grant_type – Muss auf den Wert refresh_token festgelegt sein.
  • refresh_token – Das Aktualisierungstoken, das dem zu verlängernden Zugriffstoken zugeordnet ist.

Standardmäßig sucht die Richtlinie nach diesen Elementen unter den im Anfragetext angegebenen x-www-form-urlencoded-Parametern, wie im obigen Beispiel gezeigt. Mit den Elementen <GrantType> und <RefreshToken> der OAuthV2-Richtlinie können Sie einen alternativen Speicherort für diese Eingaben konfigurieren. Weitere Informationen finden sich unter OAuthV2-Richtlinie.

Optionale Parameter

  • state – Ein String, der mit der Antwort zurückgegeben wird. Wird in der Regel verwendet, um eine websiteübergreifende Anfragefälschung zu verhindern.
  • scope – Ermöglicht das Filtern der Liste der API-Produkte, mit denen das erstellte Token verwendet werden kann. Ausführliche Informationen zu Bereichen finden sich unter Mit OAuth2-Bereichen arbeiten.

Authentifizierung

  • client_id
  • client_secret

Sie müssen Client-ID und Clientschlüssel entweder als Basis-Authentifizierungsheader (Base64-codiert) oder als Formularparameter client_id und client_secret übergeben. Weitere Informationen finden Sie unter "Anmeldedaten für die Basisauthentifizierung codieren".

Beim Aktualisieren eines Zugriffstokens werden Nutzer nicht neu authentifiziert.

Im Folgenden finden Sie eine Beispiel-Endpunktkonfiguration zum Generieren eines Zugriffstokens mit einem Aktualisierungstoken. Dabei wird die Richtlinie "RefreshAccessToken" ausgeführt.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Beispielrichtlinie

Dies ist eine grundlegende RefreshAccessToken-Richtlinie, die für die Annahme des Grant-Typs refresh_token konfiguriert ist. Informationen zu optionalen Konfigurationselementen, die mit dieser Richtlinie konfiguriert werden können, finden sich unter OAuthV2-Richtlinie.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Rückgabe

Wenn <GenerateResponse> aktiviert ist, gibt die Richtlinie eine JSON-Antwort mit dem neuen Zugriffstoken zurück. Der Grant-Typ refresh_token unterstützt sowohl die Zugriffs- als auch die neuen Aktualisierungstokens. Beispiel:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Beachten Sie: Sobald ein neues Aktualisierungstoken erstellt wurde, ist das Original ungültig.

Wenn Sie für <GenerateResponse> den Wert "true" festlegen, erhalten Sie die obige Antwort. Ist <GenerateResponse> auf "false" gesetzt, gibt die Richtlinie keine Antwort zurück. Stattdessen wird der folgende Satz Ablaufvariablen mit Daten gefüllt, die sich auf die Zugriffstoken-Erteilung beziehen.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Beispiel:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Basis-Authentifizierungsdaten codieren

Wenn Sie einen API-Aufruf zum Anfordern eines Tokens oder eines Authentifizierungscode durchführen, ist es eine bewährte, von der OAuth 2.0-Spezifikation empfohlene Methode, die Werte "client_id" und "client_secret" als HTTP-Basic-Authentifizierungsheader zu übergeben, wie in IETF RFC 2617 beschrieben. Dazu müssen Sie die beiden Werte mit einem Doppelpunkt trennen und das Ergebnis Base64-codieren.

In Pseudocode:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

In diesem Beispiel ist ns4fQc14Zg4hKFCNaSzArVuwszX95X die client_id und ZIjFyTsNgQNyxI der Clientschlüssel.

Unabhängig von der Programmiersprache, die Sie zur Berechnung des Base64-codierten Werts verwenden, ist das Base64-codierte Ergebnis für diese Client-Anmeldedaten: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Anschließend können Sie die Tokenanfrage so stellen:

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

Das Dienstprogramm curl erstellt den HTTP Basic-Header für Sie, wenn Sie die Option "-u" verwenden. Folgendes entspricht der obigen Vorgehensweise:

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

In anderen Programmierumgebungen gibt es ähnliche Tastaturkürzel zum automatischen Generieren des Base64-codierten Headers.

Hash-Tokens in der Datenbank

Um den OAuth-Zugriff zu schützen und Tokens bei einer Sicherheitsverletzung der Datenbank zu aktualisieren, können Sie in Ihrer Edge-Organisation das automatische Token-Hashing aktivieren. Ist die Funktion aktiviert, so erstellt Edge automatisch eine gehashte Version neu generierter OAuth-Zugriffs- und Aktualisierungstokens mit dem von Ihnen angegebenen Algorithmus. (Informationen zum Bulk-Hashing vorhandener Tokens folgen.) Die ent-hashten Tokens werden in API-Aufrufen verwendet. Edge validiert sie gegen die Hash-Versionen in der Datenbank.

Die folgenden Attribute auf Organisationsebene steuern das Hashing von OAuth-Tokens.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Wenn Sie bereits gehashte Tokens haben und diese bis zum Ablaufdatum behalten möchten, legen Sie folgende Eigenschaften in Ihrer Organisation fest, wobei der Hashing-Algorithmus mit dem vorhandenen Algorithmus übereinstimmt (z. B. SHA1, der frühere Edge-Standard). Wurden die Tokens nicht gehasht, so verwenden Sie PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Wenn Sie Edge Cloud-Kunde sind, wenden Sie sich an den Apigee Edge-Support, um diese Attribute für Ihre Organisation festzulegen und optional vorhandene Tokens im Bulk zu hashen.

Weitere Informationen