OAuth-Tokens von Drittanbietern verwenden

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

In diesem Thema wird erläutert, wie extern generierte Zugriffstokens, Aktualisierungstokens oder Authentifizierungscodes in den Apigee-Token-Speicher importiert werden. Sie können diese Technik verwenden, wenn Sie Apigee so konfigurieren möchten, dass Tokens validiert werden, die außerhalb von Apigee generiert werden.

Im Normalfall generiert und speichert Apigee ein OAuth-Token und gibt es an die aufrufende Anwendung zurück. Die aufrufende Anwendung stellt das Token dann beim Anfordern des Dienstes wieder in Apigee bereit und Apigee prüft anhand der OAuthV2-Richtlinie mit Operation = VerifyAccessToken, ob das Token gültig ist. In diesem Thema wird beschrieben, wie Sie Apigee konfigurieren können, um ein OAuth-Token zu speichern, das an anderer Stelle generiert wurde, ohne die Tokenverifizierung zu ändern – so, als ob das Token von Apigee generiert wurde.

Beispiel

Eine Anwendung, die das in diesem Thema beschriebene Verfahren veranschaulicht, bietet das Beispiel Apigee Delegated Token Management.

Was ist das?

Angenommen, Sie haben ein bestehendes Autorisierungssystem und möchten von diesem System generierte Tokens oder Codewerte anstelle der von Apigee generierten OAuth2-Tokens oder -Codewerte verwenden. Sie können dann sichere API-Proxy-Anfragen mit dem Ersatztoken oder -code erstellen und Apigee prüft das Token oder den Code, als ob sie von Apigee generiert wurden.

Hintergrund

Normalerweise generiert Apigee ein Token in Form eines zufälligen Strings aus Buchstaben und Zahlen. Apigee verknüpft mit diesem Token andere Daten wie den Zeitpunkt der Tokenvergabe, den Ablauf, die Liste der API-Produkte, für die das Token gültig ist, und den Bereich. Alle diese Informationen können in einer Antwort zurückgegeben werden, die automatisch von der OAuthV2-Richtlinie mit Operation = GenerateAccessToken generiert wird. Die Antwort sieht so aus:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Der Wert access_token wird von Apigee verwendet, um die Tokenmetadaten abzurufen. Angenommen, eine API-Proxy-Anfrage enthält das Inhabertoken zBC90HhCGmGlaMBWeZAai2s3za5j. Mit dem Tokenwert ruft Apigee die Tokenmetadaten ab, um festzustellen, ob das Token gültig ist oder nicht.

Mit den hier beschriebenen Schritten können Sie Apigee so konfigurieren, dass ein Token gespeichert wird, dessen access_token-Wert von einem externen Dienst generiert wurde. Angenommen, Sie haben ein System außerhalb von Apigee, das Tokens im Format "TOKEN-<16 Zufallszahlen>" generiert. In diesem Fall lauten die vollständigen, von Apigee gespeicherten Token-Metadaten z. B.:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

In diesem Fall könnte eine Anwendung eine Anfrage an einen API-Proxy senden, der das Inhabertoken TOKEN-1092837373654221 enthält, und Apigee kann es validieren. Sie können ein ähnliches Importmuster auf Autorisierungscodes und Aktualisierungstokens anwenden.

Anmeldedaten von Clients prüfen

Eine Voraussetzung für die Generierung eines Tokens ist die Prüfung des anfragenden Clients. Standardmäßig werden die Anmeldedaten des Clients mit der Richtlinie "OAuthV2/GenerateAccessToken" in Apigee Edge implizit geprüft. In einer Anfrage für ein OAuthV2-Token werden client_id und client_secret normalerweise im Autorisierungsheader übergeben. Die Verschlüsselung erfolgt über eine HTTP-Basisautorisierung (verkettet durch Doppelpunkt, dann Base64-Codierung). Die OAuthV2/GenerateAccessToken-Richtlinie in Apigee decodiert diesen Header, sucht die client_id und prüft, ob der übergebene client_secret für diese client_id gültig ist. Dies funktioniert, wenn Apigee die Anmeldedaten kennt. Mit anderen Worten: In Apigee Edge ist eine Entwickler-App gespeichert, die Anmeldedaten enthält, die wiederum die angegebene client_id und den client_secret enthalten.

Falls die Clientanmeldedaten nicht von Apigee validiert werden, müssen Sie Ihren API-Proxy so konfigurieren, dass der Client vor Generierung eines Tokens auf andere Weise explizit geprüft wird. Dies geschieht häufig über eine ServiceCallout-Richtlinie, die eine Verbindung zu einem Remote-Endpunkt in Ihrem Netzwerk herstellt.

Mit einer der beiden Methoden, entweder implizit oder explizit, müssen Sie dafür sorgen, dass der API-Proxy, der Tokens generiert, zuerst die Clientanmeldedaten validiert. Die Validierung des Clients ist unabhängig von der Generierung des Zugriffstokens. Sie können Apigee dafür konfigurieren, beides zu tun oder nur eines oder nichts davon.

Wenn die OAuthV2/GenerateAccessToken-Richtlinie in Apigee die Clientanmeldedaten anhand des Apigee-Speichers validieren soll, setzen Sie das <ExternalAuthorization>-Element in der Richtlinienkonfiguration auf false oder lassen Sie es ganz weg. Wenn Sie einen externen Autorisierungsdienst verwenden möchten, um die Anmeldedaten des Clients explizit zu validieren, setzen Sie <ExternalAuthorization> auf true.

Apigee validiert die Anmeldedaten des Clients zwar möglicherweise nicht, ist aber noch erforderlich, damit client_id bekannt ist und von Apigee verwaltet wird. Jedes access_token in Apigee, ob es von Apigee generiert wird oder von einem externen System generiert und dann in Apigee importiert wird, muss einer Clientanwendung zugeordnet sein, die durch client_id angegeben wird. Selbst wenn die OAuthV2/GenerateAccessToken-Richtlinie in Apigee nicht überprüft, ob client_id und client_secret übereinstimmen, prüft die Richtlinie, ob client_id gültig, vorhanden und nicht widerrufen ist. In diesem Fall müssen Sie möglicherweise zuvor client_ids über die administrative Apigee API importieren.

Richtlinienablauf für OAuth von Drittanbietern auf Apigee

Zur Verwendung von Tokens aus OAuth-Drittanbietersystemen in Apigee sollte der Ablauf zum Generieren von Zugriffstokens einem der folgenden Muster folgen.

Externe Validierung von Clientanmeldedaten

  1. ServiceCallout, um die eingehenden Clientanmeldedaten zu prüfen und ein externes Token abzurufen.
  2. ExtractVariables oder ein JavaScript-Schritt, um das extern generierte Token aus der Antwort zu extrahieren.
  3. AssignMessage, um die spezielle bekannte Variable oauth_external_authorization_status festzulegen. Der Wert muss "true" sein, damit die Clientanmeldedaten gültig sind.
  4. OAuthV2/GenerateAccessToken mit dem Element <ExternalAuthorization> auf true gesetzt und mindestens einem <ExternalAccessToken>, <ExternalRefreshToken> oder <ExternalAuthorizationCode>.

Interne Prüfung der Clientanmeldedaten

  • ServiceCallout, um ein externes Token abzurufen.
  • ExtractVariables oder ein JavaScript-Schritt, um das extern generierte Token aus der Antwort zu extrahieren.
  • OAuthV2/GenerateAccessToken mit dem Element <ExternalAuthorization> auf false gesetzt und mindestens einem <ExternalAccessToken>, <ExternalRefreshToken> oder <ExternalAuthorizationCode>.

Hinweise zum Ablauf und zur Richtlinienkonfiguration

  • Wenn Sie zur Überprüfung der Clientanmeldedaten ein externes System verwenden möchten, müssen Sie einen Richtlinienablauf entwickeln, der die erforderlichen Maßnahmen durchführt. Normalerweise verwenden Sie eine ServiceCallout-Richtlinie, um die extern erkannten Anmeldedaten an den externen Authentifizierungsdienst zu senden. Der externe Authentifizierungsdienst gibt in der Regel eine Antwort zurück und, falls die Anmeldedaten gültig sind, auch ein Zugriffstoken.

  • Nach der Verwendung von ServiceCallout muss der API-Proxy die Antwort parsen, um den Gültigkeitsstatus sowie das extern generierte Zugriffstoken und möglicherweise das Aktualisierungstoken zu extrahieren.

  • Setzen Sie in der OAuthV2/GenerateAccessToken-Richtlinie das Element <StoreToken> auf true und setzen Sie das Element <ExternalAuthorization> entsprechend auf true oder false.

    Wenn die OAuthV2/GenerateAccessToken-Richtlinie ausgeführt wird, liest sie die Variable oauth_external_authorization_status. Wenn die Variable festgelegt ist und der Wert "true" ist, versucht Apigee nicht, die Clientanmeldedaten zu überprüfen. Wenn die Variable nicht festgelegt oder der Wert nicht "true" ist, versucht Apigee, die Anmeldedaten des Clients zu validieren.

  • Für die OAuthV2-Richtlinie gibt es drei Elemente, mit denen Sie die zu importierenden externen Daten angeben können: <ExternalAccessToken>, <ExternalRefreshToken> und <ExternalAuthorizationCode>. Jedes dieser Elemente akzeptiert eine Ablaufvariable. Die Apigee-Richtlinie liest diese Variable, um das extern generierte Zugriffstoken, das Aktualisierungstoken oder den Autorisierungscode zu finden. Es liegt bei Ihnen, Richtlinien und Logik zu implementieren, um die externen Tokens oder Codes in den entsprechenden Variablen zu platzieren.

    Die folgende Konfiguration in der OAuthV2-Richtlinie weist z. B. Apigee an, in einer Kontextvariable mit dem Namen external_token nach dem Token zu suchen.

    <ExternalAccessToken>external_token</ExternalAccessToken>

    Diese Variable muss in einem vorherigen Schritt festgelegt werden.

  • Eine gängige Methode zum Festlegen der Variablen oauth_external_authorization_status besteht darin, eine AssignMessage-Richtlinie mit dem AssignVariable-Element so zu verwenden:

    <AssignMessage name="AssignMessage-SetVariable">
    <DisplayName>Assign Message - Set Variable</DisplayName>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

    Beachten Sie, dass diese Richtlinie vor der OAuthV2-Richtlinie mit Operation = GenerateAccessToken liegen muss.

Beispiel für eine OAuthV2-Richtlinie

Die folgende OAuthV2-Richtlinie generiert ein Zugriffstoken, wenn Apigee einen Tokenwert in der Ablaufvariable external_access_token ermittelt.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <DisplayName>OAuth v2.0 1</DisplayName>
    <Attributes/>
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

Theoretisch können Sie dieses Muster mit jedem OAuth2-Autorisierungsdienst eines Drittanbieters anwenden.