OAuth-Tokens von Drittanbietern verwenden

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 außerhalb von Apigee generierte Tokens validiert 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": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Der Wert des Attributs access_token ist der Suchschlüssel für alle anderen Daten, die in diesen Metadaten enthalten sind. Eine Anwendung könnte eine Anfrage an einen in Apigee gehosteten API-Proxy mit dem Inhabertoken zBC90HhCGmGlaMBWeZAai2s3za5j stellen und Apigee würde über die OAuthV2-Richtlinie mit Operation = VerifyAccessToken das Token und alle Informationen abrufen und anhand dieser Informationen bestimmen, ob das Token für den angeforderten API-Proxy gültig ist oder nicht. Dies wird als Tokenvalidierung bezeichnet. Alle oben aufgeführten Informationen umfassen das Token. Der Wert "access_token" ist nur die Möglichkeit, diese Informationen abzurufen.

Andererseits können Sie Apigee anhand der hier beschriebenen Schritte konfigurieren, um ein Token zu speichern, sodass der Wert für access_token von einem externen Dienst generiert wird. Alle anderen Metadaten können identisch sein. Angenommen, Sie haben ein System außerhalb von Apigee, das Tokens im Format "TOKEN-<16 Zufallszahlen>" generiert. In diesem Fall können die vollständigen von Apigee gespeicherten Token-Metadaten so lauten:

{
  "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": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

In diesem Fall könnte eine Anwendung eine Anfrage an einen in Apigee gehosteten API-Proxy mit dem Inhabertoken TOKEN-1092837373654221 stellen, und Apigee wäre über die OAuthV2-Richtlinie mit Operation = VerifyAccessToken in der Lage, es zu 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 konfigurieren, um beide Aufgaben, nur eine der Aufgaben oder keine der Aufgaben auszuführen.

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

Apigee validiert die Clientanmeldedaten möglicherweise nicht. Dennoch ist es erforderlich, dass client_id bekannt ist und von Apigee verwaltet wird. Jedes access_token in Apigee, ob es von Apigee generiert oder von einem externen System generiert und dann in Apigee importiert wurde, muss einer Clientanwendung zugeordnet sein, die durch client_id angegeben wird. Selbst wenn die OAuthV2/GenerateAccessToken-Richtlinie in Apigee nicht prüft, ob client_id und client_secret übereinstimmen, wird geprüft, ob client_id gültig und vorhanden ist und nicht widerrufen wurde. In diesem Fall müssen Sie möglicherweise client_ids über die Apigee Administrative API importieren, bevor Sie die Konfiguration vornehmen.

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 einen 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 Client-Anmeldedaten 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 einen 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 Validierung der Anmeldedaten von Kunden ein externes System verwenden möchten, müssen Sie einen Richtlinienfluss entwickeln, der die erforderlichen Aufgaben ausfü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 und, falls die Anmeldedaten gültig sind, auch ein Zugriffstoken zurück.

  • 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 und der Wert "true" ist, versucht Apigee nicht, die Clientanmeldedaten zu validieren. Wenn die Variable nicht festgelegt oder der Wert nicht "true" ist, versucht Apigee, die Clientanmeldedaten 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 Flussvariable. 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.

    Durch die folgende Konfiguration in der OAuthV2-Richtlinie wird beispielsweise Apigee angewiesen, in einer Kontextvariable namens 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>
    <Tokens/>
</OAuthV2>

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