Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
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.
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 Optional können Sie das Element |
– | Erforderlich |
continueOnError |
Legen Sie Legen Sie |
falsch | Optional |
enabled |
Setzen Sie den Wert auf Legen Sie |
true | Optional |
async |
Dieses Attribut wurde verworfen. |
false | Verworfen |
<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>
Standard |
– Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs |
---|---|
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.
<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.
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>