GetOAuthV2Info-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Die JWT-Zugriffstoken-Funktion ist derzeit für Apigee und für die Apigee Hybrid-Versionen 1.7.0 und höher verfügbar. Siehe JWT-OAuth-Tokens verwenden.

Was

Ruft Attribute von Zugriffstokens, Aktualisierungstokens, Autorisierungscodes und Clientanwendungsattributen ab und füllt Variablen mit den Werten dieser Attribute aus.

Diese Richtlinie ist nützlich, wenn Sie das dynamische, bedingte Verhalten basierend auf einem Wert in einem Token oder Authentifizierungscode konfigurieren müssen. Bei der Tokenvalidierung werden Variablen automatisch mit den Werten der Tokenattribute gefüllt. Wenn jedoch keine Tokenvalidierung durchgeführt wurde, können Sie diese Funktion verwenden, um Variablen explizit mit den Attributwerten eines Tokens zu füllen. Siehe Token und Autorisierungscodes anpassen.

Ein Zugriffstoken, das Sie an diese Richtlinie übergeben, muss gültig sein oder die Richtlinie gibt den Fehler invalid_access_token aus.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

HINWEIS

Der Ressourcenpfad, der zum Aufrufen eines Proxys mit dieser Richtlinie verwendet wird, muss in dem Produkt enthalten sein, mit dem das ursprüngliche Token generiert wurde. Das heißt, wenn Sie den Proxy mit dem Pfad /tokeninfo aufrufen, muss der Ressourcenpfad /tokeninfo in dem Produkt enthalten sein, mit dem das Token generiert wurde. Andernfalls wird der Fehler InvalidAPICallAsNoApiProductMatchFound zurückgegeben.

Weitere Informationen finden Sie in der Apigee-Community unter GetOAuthV2Info schlägt fehl, wenn Token mit Produkt mit Ressourcenpfaden generiert wurde.

Beispiele

In den folgenden Beispielen werden mit der GetOAuth v2-Informationsrichtlinie Informationen zu verschiedenen Komponenten des OAuth2-Workflows abgerufen und anschließend wird innerhalb von Code auf diese Informationen zugegriffen.

Zugriffstoken

Verwenden Sie das Element <AccessToken> in Ihrer Richtlinie, um einen Verweis auf ein Zugriffstoken zu erhalten.

Im folgenden Beispiel wird davon ausgegangen, dass das Zugriffstoken in einem Abfrageparameter mit dem Namen „access_token“ gefunden wird. Die tatsächlichen Implementierungsdetails können Sie selbst bestimmen:

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

Anhand des Zugriffstokens sucht die Richtlinie das Profil des Tokens und fügt eine Reihe von Variablen mit den Profildaten ein.

Sie können dann mithilfe von JavaScript oder einer anderen Methode auf die Variablen zugreifen. Im folgenden Beispiel werden die mit dem Zugriffstoken verknüpften Bereiche mithilfe von JavaScript abgerufen:

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

Beachten Sie, dass Sie den Variablen "oauthv2accesstoken" voranstellen müssen, um auf diese Variablen im Code zuzugreifen. Eine vollständige Liste der über das Zugriffstoken verfügbaren Variablen finden Sie unter Zugriffstoken-Variablen.

Auth-Code

Verwenden Sie das Element <AuthorizationCode> in Ihrer Richtlinie, um Autorisierungscodeattribute abzurufen.

Im folgenden Beispiel wird davon ausgegangen, dass das Zugriffstoken in einem Formularparameter mit dem Namen "code" gefunden wird. Die tatsächlichen Implementierungsdetails liegen bei Ihnen:

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

Anhand des Authentifizierungscodes ruft die Richtlinie die Informationen des Codes ab und füllt eine Reihe von Variablen mit den Daten des Authentifizierungscodes aus.

Sie können dann mithilfe von JavaScript oder einer anderen Methode auf die Variablen zugreifen. Im folgenden Beispiel wird mit JavaScript ein benutzerdefiniertes Attribut abgerufen, das mit dem Autorisierungscode verknüpft ist:

var attr = context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

Wenn Sie auf diese Variablen im Code zugreifen möchten, müssen Sie ihnen das Präfix "oauthv2authcode" voranstellen. Eine vollständige Liste der über den Authentifizierungscode verfügbaren Variablen finden Sie unter Autorisierungscodevariablen.

Aktualisierungstoken

Verwenden Sie zum Abrufen von Aktualisierungstokenattributen das Element <RefreshToken> in Ihrer Richtlinie.

Im folgenden Beispiel wird erwartet, dass das Zugriffstoken in einem Abfrageparameter mit dem Namen "refresh_token" gefunden wird (die tatsächlichen Implementierungsdetails liegen bei Ihnen):

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

Anhand dem Aktualisierungstoken sucht die Richtlinie nach den Informationen des Aktualisierungstokens und füllt in eine Reihe von Variablen die Daten des Aktualisierungstokens ein.

Sie können dann mithilfe von JavaScript oder einer anderen Methode auf diese Variablen zugreifen. Im folgenden Beispiel wird ein benutzerdefiniertes Attribut, das dem Aktualisierungstoken zugeordnet ist, mithilfe von JavaScript abgerufen:

var attr = context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

Beachten Sie, dass Sie den Variablen "oauthv2refreshtoken" voranstellen müssen, um auf die Variablen im Code zuzugreifen. Eine vollständige Liste der über das Aktualisierungstoken verfügbaren Variablen finden Sie unter Tokenvariablen aktualisieren.

Statisch

In seltenen Fällen müssen Sie das Profil eines statisch konfigurierten Tokens abrufen (eines, auf das nicht über eine Variable zugegriffen werden kann). Geben Sie dazu den Wert des Zugriffstokens als Element an.

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

Dies ist auch mit allen anderen Tokentypen (Client-ID, Autorisierungscode und Aktualisierungstoken) möglich.

Client-ID

Dieses Beispiel zeigt, wie Sie mithilfe der Client-ID Informationen zur Clientanwendung abrufen. Bei der Ausführung fügt die Richtlinie eine Reihe von Variablen mit Clientinformationen ein. In diesem Fall erwartet die Richtlinie die Client-ID in einem Abfrageparameter namens client_id. Anhand der Client-ID sucht die Richtlinie nach dem Profil des Clients und füllt eine Reihe von Variablen mit den Profildaten. Den Variablen wird das Präfix oauthv2client. vorangestellt.

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

Sie können dann mithilfe von JavaScript oder einer anderen Methode auf die Variablen zugreifen. So rufen Sie beispielsweise den Namen der Entwickleranwendung und die Entwickler-E-Mail-Adresse mithilfe von JavaScript ab:

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

---

Elementreferenz

Die Elementreferenz beschreibt die Elemente und Attribute der Richtlinie „RevokeOAuthV2“.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

<GetOAuthV2Info> Attribute

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

Attribut	Beschreibung	Standard	Präsenz
name	Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten. Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.	–	Erforderlich
continueOnError	Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf	falsch	Optional
enabled	Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.	true	Optional
async	Dieses Attribut wurde verworfen.	false	Veraltet

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>

Standardeinstellung	– Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Präsenz	Optional
Typ	String

<AccessToken>-Element

Ruft das Profil für ein Zugriffstoken ab. Sie übergeben entweder eine Variable, die den Zugriffstoken-String enthält, oder einen String-Token-String (Groß- und Kleinschreibung). In diesem Beispiel wird das Zugriffstoken von einem Suchparameter abgerufen, der in einer Anfrage übergeben wird. Verwenden Sie das Element <IgnoreAccessTokenStatus>, wenn Sie Informationen zu einem zurückgezogenen oder abgelaufenen Token abrufen möchten.

<AccessToken ref="request.queryparam.access_token"></AccessToken>

Standard:	request.formparam.access_token (ein x-www-form-urlencoded und im Anfrage-Text angegeben)
Präsenz:	Optional
Typ:	String
Zulässige Werte:	Entweder eine Ablaufvariable mit einem Zugriffstokenstring oder einen Literalstring.

<AuthorizationCode>-Element

Ruft das Profil für einen Autorisierungscode ab. Sie übergeben entweder eine Variable, die den Authentifizierungscode-String enthält, oder einen Literaltoken-String (Groß- und Kleinschreibung). In diesem Beispiel wird der Authentifizierungscode von einem Suchparameter abgerufen, der in einer Anfrage übergeben wird. Eine Liste der Variablen, die von diesem Vorgang ausgefüllt werden, finden Sie unter Ablaufvariablen.

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

Standard:	request.formparam.access_token (ein x-www-form-urlencoded und im Anfrage-Text angegeben)
Präsenz:	Optional
Typ:	String
Zulässige Werte:	Entweder eine Ablaufvariable mit einem Authentifizierungscodestring oder einen Literalstring.

<ClientId>-Element

Ruft Informationen zu einer Client-ID ab. In diesem Beispiel wird die Client-ID von einem Suchparameter abgerufen, der in einer Anfrage übergeben wird. Eine Liste der Variablen, die von diesem Vorgang ausgefüllt werden, finden Sie unter Ablaufvariablen.

<ClientId ref="request.queryparam.client_id"></ClientId>

Standard:	request.formparam.access_token (ein x-www-form-urlencoded und im Anfrage-Text angegeben)
Präsenz:	Optional
Typ:	String
Zulässige Werte:	Entweder eine Ablaufvariable mit einem Authentifizierungscodestring oder einen Literalstring.

Element <IgnoreAccessTokenStatus>

Gibt die Tokeninformationen zurück, auch wenn das Token abgelaufen ist oder widerrufen wurde. Dieses Element kann nur mit Zugriffstokens verwendet werden. Informationen für andere Entitäten wie Aktualisierungstokens und Autorisierungscodes werden standardmäßig unabhängig von ihrem Status zurückgegeben.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Standard:	false
Präsenz:	Optional
Typ:	Boolesch
Zulässige Werte:	richtig oder falsch

<RefreshToken>-Element

Ruft das Profil für ein Aktualisierungstoken ab. Sie übergeben entweder eine Variable, die den Aktualisierungstoken-String enthält, oder einen Literaltoken-String (selten). In diesem Beispiel wird das Aktualisierungstoken von einem Abfrageparameter abgerufen, der in einer Anfrage übergeben wird. Eine Liste der Variablen, die von diesem Vorgang ausgefüllt werden, finden Sie unter Ablaufvariablen.

Hinweis: Dieses Element funktioniert genauso, wenn Sie ein Aktualisierungstoken verwenden, das mit einem JWT-Zugriffstoken oder einem herkömmlichen intransparenten Zugriffstoken ausgegeben wurde.

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

Standard:	request.formparam.access_token (ein x-www-form-urlencoded und im Anfrage-Text angegeben)
Präsenz:	Optional
Typ:	String
Zulässige Werte:	Entweder eine Ablaufvariable mit einem Aktualisierungstokenstring oder einen Literalstring.

Ablaufvariablen

Die GetOAuthV2Info-Richtlinie füllt diese Variablen aus und wird in der Regel verwendet, wenn Sie die Profildaten benötigen, aber noch keine Erteilung oder Validierung erfolgt ist. .

Client-ID-Variablen

Diese Variablen werden ausgefüllt, wenn das ClientId-Element festgelegt wird:

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

Zugriffstoken-Variablen

Diese Variablen werden ausgefüllt, wenn das Zugriffstoken-Element festgelegt ist:

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Autorisierungscode-Variablen

Diese Variablen werden ausgefüllt, wenn das AuthorizationCode-Element festgelegt wird:

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope
oauthv2authcode.{policy_name}.redirect_uri
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

Aktualisierungstoken-Variablen

Diese Variablen werden ausgefüllt, wenn das Aktualisierungstoken-Element festgelegt wird:

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Schema

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten. Die unten aufgeführten Fehlernamen sind die Strings, die der Variable fault.name zugewiesen sind, wenn ein Fehler auftritt. Weitere Informationen finden Sie unten im Abschnitt "Fehlervariablen".

Fehlercode	HTTP-Status	Ursache
steps.oauth.v2.access_token_expired	500	Das an die Richtlinie gesendete Zugriffstoken ist abgelaufen.
steps.oauth.v2.authorization_code_expired	500	Der an die Richtlinie gesendete Autorisierungscode ist abgelaufen.
steps.oauth.v2.invalid_access_token	500	Das an die Richtlinie gesendete Zugriffstoken ist ungültig.
steps.oauth.v2.invalid_client-invalid_client_id	500	Die an die Richtlinie gesendete Client-ID ist ungültig.
steps.oauth.v2.invalid_refresh_token	500	Das an die Richtlinie gesendete Aktualisierungstoken ist ungültig.
steps.oauth.v2.invalid_request-authorization_code_invalid	500	Der an die Richtlinie gesendete Autorisierungscode ist ungültig.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	Informationen zur Fehlerbehebung finden Sie unter Fehler bei der OAuth 2.0-Zugriffstoken-Bestätigung mit dem Fehler „Invalid API call as no apiproduct match found”.
steps.oauth.v2.refresh_token_expired	500	Das an die Richtlinie gesendete Aktualisierungstoken ist abgelaufen.

Bereitstellungsfehler

Informationen zu Bereitstellungsfehlern finden Sie in der Benutzeroberfläche, die in der Benutzeroberfläche angezeigt wird.

Fehlervariablen

Diese Variablen werden festgelegt, wenn diese Richtlinie zur Laufzeit einen Fehler auslöst.

Hinweis: Sie verwenden diese Variablen, um Bedingungen für Fehlerregeln zu erstellen. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Variablen	Wo	Beispiel
fault.name="fault_name"	fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes.	fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed	policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	oauthV2.GetTokenInfo.cause = ClientID is Invalid

Beispiel für eine Fehlerantwort

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Beispiel für eine Fehlerregel

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

Weitere Informationen

• OAuthV2-Richtlinie
• OAuth-Startseite
• Tokens und Autorisierungscodes anpassen