SetOAuth v2-Informationsrichtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Was

Ermöglicht das Hinzufügen oder Aktualisieren von benutzerdefinierten Attributen, die mit einem Zugriffstoken verknüpft sind. Benutzerdefinierte Attribute können beispielsweise den Namen einer Abteilung, eine Kundennummer oder eine Sitzungs-ID enthalten. Siehe Token und Autorisierungscodes anpassen.

Sie können benutzerdefinierte Attribute nur hinzufügen oder ändern. Sie können diese Richtlinie nicht verwenden, um Felder wie "Scope", "status", "expires_in", "developer_email", "client_id", "org_name" oder "refresh_count" zu ändern. Wenn ein Attribut bereits vorhanden ist, wird es durch diese Richtlinie aktualisiert. Wenn sie nicht vorhanden ist, wird sie von der Richtlinie hinzugefügt. Das referenzierte Zugriffstoken muss gültig sein und den Status "Genehmigt" haben.

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

Einfaches Beispiel

Im Folgenden finden Sie eine Beispielrichtlinie, die zum Aktualisieren eines OAuth 2.0-Zugriffstokens verwendet wird. Im folgenden Beispiel wird das Zugriffstoken für die Anfragenachricht über den Suchparameter access_token gesucht. Wenn ein Zugriffstoken von einer Client-App bereitgestellt wird, sucht die Richtlinie unten das Zugriffstoken im Suchparameter. Anschließend wird das Profil des Zugriffstokens aktualisiert. Dem Profil wird eine benutzerdefinierte Eigenschaft namens department.id hinzugefügt.

<SetOAuthV2Info name="SetOAuthV2Info"> 
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
  </Attributes>
</SetOAuthV2Info>

Hinweis: Wenn im Profil des Zugriffstokens bereits ein Attribut vorhanden ist, wird es mit dem neuen Wert in der Richtlinie aktualisiert. Wenn ein Attribut nicht vorhanden ist, wird das Attribut dem Profil des Zugriffstokens hinzugefügt.

---

Elementreferenz

Die Elementreferenz beschreibt die Elemente und Attribute der SetOAuthV2-Richtlinie.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="SetOAuthV2Info-1">    
    <DisplayName>Set OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref={some-variable}></AccessToken>
    <Attributes/>
</SetOAuthV2Info>
</xml>

<SetOAuthV2Info>-Attribute

<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Set-OAuth-v20-Info-1">

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

Attribut	Beschreibung	Standard	Presence
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. Siehe auch: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf	false	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	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 name der Richtlinie verwendet.
Presence	Optional
Typ	String

<AccessToken>-Element

Gibt die Variable an, in der sich das Zugriffstoken befindet. Wenn beispielsweise das Zugriffstoken an die Anfragenachricht als Suchparameter angehängt ist, geben Sie request.queryparam.access_token an. Sie können jede gültige Variable verwenden, die auf das Token verweist. Alternativ könnte der literalen Tokenstring verwendet werden (selten).

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

Standard:	–
Präsenz:	Erforderlich
Typ:	String

Attribute

Attribut	Beschreibung	Standard	Presence
ref	Eine Variable für das Zugriffstoken. Wird normalerweise aus einer Ablaufvariablen abgerufen.	–	Optional

<Attributes>-Element

Eine Reihe von Attributen im Zugriffstokenprofil, die geändert oder erweitert werden.

Standard:	–
Präsenz:	Erforderlich
Typ:	–

<Attributes>/<Attribute>-Element

Ein einzelnes zu aktualisierendes Attribut.

Das Namensattribut gibt die benutzerdefinierte Eigenschaft des Zugriffstokens an, das aktualisiert werden soll. In diesem Beispiel wird gezeigt, wie ein referenzierter Variablenwert und ein statischer Wert verwendet werden.

  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
    <Attribute name="foo">bar</Attribute>
  </Attributes>

Standard:	–
Präsenz:	Optional
Typ:	–

Attribute

Attribut	Beschreibung	Standard	Presence
Name	Der Name des Profilattributs, das Sie hinzufügen oder ändern möchten.	–
Ref	Der Wert, der dem Profilattribut zugewiesen werden soll.	–	Optional

Ablaufvariablen

Bei Erfolg werden die folgenden Ablaufvariablen festgelegt:

• oauthv2accesstoken.{policyName}.access_token
• oauthv2accesstoken.{policyName}.client_id
• oauthv2accesstoken.{policyName}.refresh_count
• oauthv2accesstoken.{policyName}.organization_name
• oauthv2accesstoken.{policyName}.expires_in //--in seconds
• oauthv2accesstoken.{policyName}.refresh_token_expires_in //--in seconds
• oauthv2accesstoken.{policyName}.issued_at
• oauthv2accesstoken.{policyName}.status
• oauthv2accesstoken.{policyName}.api_product_list
• oauthv2accesstoken.{policyName}.token_type
• oauthv2accesstoken.{policyName}.{custom_attribute_name}

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.

Fehlercode	HTTP-Status	Ursache
steps.oauth.v2.access_token_expired	500	Das an die Richtlinie gesendete Zugriffstoken ist abgelaufen.
steps.oauth.v2.invalid_access_token	500	Das an die Richtlinie gesendete Zugriffstoken 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”.

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 = "invalid_access_token"
oauthV2.policy_name.failed	policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	oauthV2.SetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	oauthV2.SetTokenInfo.fault.name = invalid_access_token
oauthv2.policy_name.fault.cause	policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	oauthV2.SetTokenInfo.cause = Invalid Access Token

Beispiel für eine Fehlerantwort

{
  "fault": {
    "faultstring": "Invalid Access Token",
    "detail": {
      "errorcode": "keymanagement.service.invalid_access_token"
    }
  }
}

Beispiel für eine Fehlerregel

<FaultRule name=SetOAuthV2Info Faults">
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Weitere Informationen

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