OAuthV2-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Was

OAuthV2 ist eine mehrzeilige Richtlinie für die Durchführung von OAuth 2.0-Berechtigungstypen. Dies ist die Hauptrichtlinie zum Konfigurieren von OAuth 2.0-Endpunkten in Apigee.

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.

Weitere Informationen zu OAuth in Apigee finden Sie auf der OAuth-Startseite. Sie enthält Links zu Ressourcen, Beispielen, Videos und mehr.

Tipp: In der VerifyIAM-Richtlinie finden Sie eine Standardrichtlinie, die eine in Google Cloud IAM integrierte Methode zum Verwalten der Authentifizierung und Autorisierung bei einem Proxy bietet.

Beispiele

VerifyAccessToken

VerifyAccessToken

Diese OAuthV2-Richtlinienkonfiguration (mit dem VerifyAccessToken-Vorgang) überprüft, ob ein an Apigee gesendetes Zugriffstoken gültig ist. Wenn dieser Richtlinienvorgang ausgelöst wird, sucht Apigee in der Anfrage nach einem gültigen Zugriffstoken. Wenn das Zugriffstoken gültig ist, kann die Anfrage fortgesetzt werden. Wenn es ungültig ist, wird die Verarbeitung beendet und in der Antwort wird ein Fehler zurückgegeben.

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Hinweis: Es werden nur OAuth 2.0-Inhabertoken unterstützt. Andere Arten von Tokens wie MAC-Tokens (Message Authentication Code) werden nicht unterstützt.

Eine Clientanwendung muss eine Anfrage mit einem Token senden. Zum Beispiel mit curl:

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

Dabei ist API_ENDPOINT die Domain, die für den Zugriff auf Ihre APIs verwendet wird, wie in Ihrem Apigee-System konfiguriert.

Standardmäßig extrahiert die OAuthV2-Richtlinie das Zugriffstoken aus dem Header Authorization und entfernt das Präfix Bearer. Sie können dieses Standardverhalten mit dem Konfigurationselement AccessToken ändern.

GenerateAccessToken

Zugriffstokens generieren

Beispiele dafür, wie Sie Zugriffstokens für die unterstützten Berechtigungstypen anfordern, finden Sie unter OAuth 2.0-Tokens abrufen. Das Thema enthält Beispiele für diese Vorgänge:

• Autorisierungscode
• Clientanmeldedaten
• Implizit
• Passwort

Hinweis: Mit dem GenerateAccessToken-Vorgang kann die OAuthV2-Richtlinie eine Antwort zurückgeben, die nicht vollständig den zugehörigen OAuth 2.0-Spezifikationen entspricht. Ein Beispiel: Die Property token_type in der Tokenantwort ist möglicherweise nicht konform. Weitere Informationen zu diesem und anderen möglichen nicht konformen Antwortelementen finden Sie unter RFC-konformes Verhalten.

GenerateAuthorizationCode

Autorisierungscode generieren

Beispiele zum Anfordern von Autorisierungscodes finden Sie unter Autorisierungscode anfordern.

RefreshAccessToken

Zugriffstoken aktualisieren

Beispiele zum Anfordern von Zugriffstokens mit einem Aktualisierungstoken finden Sie unter Zugriffstoken aktualisieren.

JWT-Zugriffstokens

JWT-Zugriffstokens

Beispiele zum Generieren, Verifizieren und Aktualisieren von JWT-Zugriffstokens finden Sie unter JWT-Zugriffstokens verwenden.

Antwortfluss-Token

Generieren Sie ein Zugriffstoken für den Antwortfluss

Manchmal müssen Sie im Antwortfluss ein Zugriffstoken generieren. Dies können Sie beispielsweise als Reaktion auf eine benutzerdefinierte Validierung in einem Back-End-Dienst tun. In diesem Beispiel sind für den Anwendungsfall sowohl ein Zugriffstoken als auch ein Aktualisierungstoken erforderlich. Damit wird der implizite Gewährungstyp weggelassen. In diesem Fall verwenden wir die Passwortzuweisung, um das Token zu generieren. Wie Sie sehen, wird bei dieser Arbeit durch die Übergabe eines Autorisierungsanfrageheader mit einer JavaScript-Richtlinie umgangen.

Betrachten wir zuerst die Beispielrichtlinie:

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

Wenn Sie diese Richtlinie in den Antwortfluss einfügen, schlägt die Fehlermeldung mit dem Fehler 401 UnAuthorized vor, obwohl die korrekten Anmeldeparameter in der Richtlinie angegeben sind. Um dieses Problem zu lösen, müssen Sie einen Autorisierungsanfrageheader festlegen.

Der Autorisierungsheader muss ein Basiszugriffsschema mit der Base64-codierten client_id:client_secret enthalten.

Sie können diesen Header mit einer JavaScript-Richtlinie hinzufügen, die unmittelbar vor der OAuthV2-Richtlinie platziert wird, z. B. so: Die Kontextvariablen "local_clientid" und "local_secret" müssen zuvor festgelegt und im Ablauf verfügbar sein:

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

Warnung:Bei VerifyAPIKey- und OAuthV2-Richtlinien kann es unter bestimmten Umständen zu erhöhten Latenzen im P90+-Bereich kommen. Dieses Verhalten ist in der Regel zu beobachten, wenn die Rate für Abfragen pro Sekunde (Queries Per Second, QPS) sehr niedrig ist (einstellige Rate) und Message Processors (MPs) überdimensioniert sind. Die erhöhte Latenz in diesen Szenarien ist hauptsächlich auf eine ineffiziente Cache-Nutzung zurückzuführen.

Weitere Informationen finden Sie unter Anmeldedaten für die Basisauthentifizierung codieren.

Elementverweis

In der Richtlinienreferenz werden die Elemente und Attribute der OAuthV2-Richtlinie beschrieben.

Hinweis: Die Art und Weise, wie Sie diese Richtlinie konfigurieren, und die Elemente, die Sie angeben müssen, hängen vom Vorgang ab, der die Richtlinie ausführen soll. Wenn Sie beispielsweise die Autorisierungsart für den Autorisierungscode implementieren, benötigen Sie vier separate OAuthV2-Richtlinien, um den Autorisierungscode zu generieren, auf die Codegenerierung zuzugreifen und die Tokenerzeugung zu aktualisieren. In dieser Referenz werden alle Elemente aufgelistet, die mit dieser Richtlinie verwendet werden können.

Wenn Sie sich Konfigurationen für bestimmte Berechtigungstypen ansehen möchten, finden Sie auf der OAuth-Startseite eine Liste der Implementierungsarten.

Die unten aufgeführte Beispielrichtlinie ist eine von vielen möglichen Konfigurationen. Dieses Beispiel zeigt eine OAuthV2-Richtlinie, die für den GenerateAccessToken-Vorgang konfiguriert wurde. Sie enthält erforderliche und optionale Elemente. Weitere Informationen finden Sie in den Elementbeschreibungen in diesem Abschnitt.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2>-Attribute

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

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

<AccessToken>request.header.access_token</AccessToken>

Wenn Operation den Wert VerifyAccessToken hat, erwartet die Richtlinie standardmäßig, dass das Zugriffstoken im Authorization-Header als Inhabertoken gesendet wird, d. h. mit dem Präfix „Inhaber“ gefolgt von einem Leerzeichen. Sie können diesen Standardwert mit diesem Element ändern und den Namen einer Variablen angeben, die das zu bestätigende Zugriffstoken enthält. Wenn Sie dieses Element verwenden, sucht die Richtlinie standardmäßig nicht nach einem Präfix im Inhalt der Variablen. Wenn Sie angeben möchten, dass die Richtlinie nach einem Präfix suchen soll, verwenden Sie auch das Element AccessTokenPrefix.

Beispiele:

• Wenn die Richtlinienkonfiguration lautet:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.header.access_token</AccessToken>
    </OAuthV2>

  Zum Übergeben des Tokens mit curl können Sie Folgendes verwenden:

    curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

• Wenn die Richtlinienkonfiguration lautet:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.queryparam.token</AccessToken>
    </OAuthV2>

  Zum Übergeben des Tokens mit curl können Sie Folgendes verwenden:

    curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

Dabei ist API_ENDPOINT die Domain, die für den Zugriff auf Ihre APIs verwendet wird, wie in Ihrem Apigee-System konfiguriert.

Default	–
Präsenz	Optional
Typ	String
Zulässige Werte	Beliebiger Variablenname
Wird bei Vorgängen verwendet	VerifyAccessToken

<AccessTokenPrefix> -Element

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

Wenn Operation den Wert VerifyAccessToken hat, erwartet die Richtlinie standardmäßig, dass das Zugriffstoken im Authorization-Header als Inhabertoken gesendet wird, d. h. mit dem Präfix „Inhaber“ gefolgt von einem Leerzeichen. Wenn Sie das Element AccessToken verwenden, um einen anderen Speicherort für das eingehende Zugriffstoken anzugeben, können Sie das Element AccessTokenPrefix auch verwenden, um ein anderes, nicht standardmäßiges Präfix anzugeben.

Wenn Sie beispielsweise angeben:

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

Dann extrahiert die Richtlinie das eingehende Zugriffstoken aus dem token-Anfrageheader, und zwar folgendermaßen: Wenn der Header mit dem Wort „SCHLÜSSEL“ beginnt, gefolgt von einem Leerzeichen, entfernt die Richtlinie dieses Präfix und das Leerzeichen und interpretiert den verbleibenden Wert als Zugriffstoken. Wenn das angegebene Präfix nicht im Header vorhanden ist, gibt die Richtlinie einen Fehler aus.

Wenn Sie das Element AccessToken, aber nicht das Element AccessTokenPrefix angeben, interpretiert die Richtlinie den gesamten Wert der Variable, die im Element AccessToken angegeben ist, als Zugriffstoken.

Dieses Element ist nur wirksam, wenn auch das Element AccessToken verwendet wird.

Default	-keine-
Präsenz	Optional
Typ	String
Zulässige Werte	beliebiger String
Wird bei Vorgängen verwendet	VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Gibt den Verschlüsselungsalgorithmus an, der zum Signieren eines JWT-Zugriffstokens verwendet wird. RSA-Algorithmen (RS*-Algorithmen) verwenden ein Paar aus öffentlichem/geheimem Schlüssel und HMAC-Algorithmen (HS*) ein gemeinsames Secret. Dieses Element ist für die Vorgänge GenerateJWTAccessToken, VerifyJWTAccessToken und RefreshJWTAccessToken erforderlich.

Standard	–
Präsenz	Erforderlich bei Verwendung der Vorgänge GenerateJWTAccessToken, VerifyJWTAccessToken und RefreshJWTAccessToken.
Typ	String
Zulässige Werte	HS256, HS384, HS512, RS256, RS384, RS512

<AppEndUser>-Element

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

In Fällen, in denen die Endnutzer-ID der Anwendung an den Autorisierungsserver gesendet werden muss, können Sie mit diesem Element angeben, wo Apigee nach der Endnutzer-ID suchen soll. Sie kann beispielsweise als Abfrageparameter oder in einem HTTP-Header gesendet werden.

Der Wert request.queryparam.app_enduser gibt beispielsweise an, dass AppEndUser als Abfrageparameter vorhanden sein soll, z. B. ?app_enduser=[e-mail]. Wenn der AppEndUser beispielsweise in einem HTTP-Header erforderlich sein soll, legen Sie diesen Wert auf request.header.app_enduser fest.

Mit dieser Einstellung können Sie eine Anwendungsendnutzer-ID in das Zugriffstoken aufnehmen. Diese Funktion ist nützlich, wenn Sie OAuth 2.0-Zugriffstoken nach Endnutzer-ID abrufen oder widerrufen möchten. Weitere Informationen finden Sie unter Abrufen und Widerrufen von OAuth 2.0-Zugriffstokens nach Endnutzer-ID, Anwendungs-ID oder beidem.

Default	–
Präsenz	Optional
Typ	String
Zulässige Werte	Jede Ablaufvariable, auf die die Richtlinie zur Laufzeit zugreifen kann.
Wird mit Berechtigungstypen verwendet	authorization_code implizit Passwort client_credentials

<Attribute/Attribut>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Verwenden Sie dieses Element, um einem Zugriffstoken oder Autorisierungscode benutzerdefinierte Attribute hinzuzufügen. Sie möchten beispielsweise eine Nutzer-ID oder Sitzungs-ID in ein Zugriffstoken einbetten, das zur Laufzeit extrahiert und überprüft werden kann.

Mit diesem Element können Sie einen Wert in einer Ablaufvariable oder aus einem Literalstring angeben. Wenn Sie sowohl eine Variable als auch einen String angeben, wird der in der Ablaufvariable angegebene Wert verwendet. Wenn die Variable nicht aufgelöst werden kann, ist der String der Standardwert.

Weitere Informationen zur Verwendung dieses Elements finden Sie unter Tokens und Autorisierungscodes anpassen.

Hinweise:

Sie können bis zu 18 benutzerdefinierte Attribute erstellen.

Wenn Sie einem Autorisierungscode benutzerdefinierte Attribute hinzufügen, werden diese Attribute vom Zugriffstoken übernommen, das von diesem Code generiert wird.

Benutzerdefinierte Attribute in der Antwort ein- oder ausblenden

Wenn Sie für das Element "GenerateResponse" dieser Richtlinie den Wert true festlegen, wird die vollständige JSON-Darstellung des Tokens einschließlich der von Ihnen festgelegten benutzerdefinierten Attribute in der Antwort zurückgegeben. In einigen Fällen möchten Sie möglicherweise einige oder alle benutzerdefinierten Attribute in der Antwort ausblenden, damit sie für Clientanwendungen nicht sichtbar sind.

Standardmäßig werden benutzerdefinierte Attribute in der Antwort angezeigt. Wenn Sie sie ausblenden möchten, können Sie für den Parameter display den Wert false festlegen. Beispiel:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Der Wert des Attributs display wird nicht beibehalten. Beispiel: Sie generieren ein Zugriffstoken mit benutzerdefinierten Attributen, die in der generierten Antwort ausgeblendet werden sollen. Mit der Einstellung display=false wird dieses Ziel erreicht. Wenn Sie später ein neues Zugriffstoken mit einem Aktualisierungstoken generieren, werden die ursprünglichen benutzerdefinierten Attribute aus dem Zugriffstoken in der Antwort des Aktualisierungstokens angezeigt. Dies liegt daran, dass Apigee nicht weiß, dass das Attribut display ursprünglich in der Richtlinie zum Generieren eines Zugriffstokens auf false gesetzt war. Das benutzerdefinierte Attribut ist einfach Teil der Metadaten des Zugriffstokens.

Dasselbe Verhalten wird erreicht, wenn Sie einem Autorisierungscode benutzerdefinierte Attribute hinzufügen. Wenn mit diesem Code ein Zugriffstoken generiert wird, werden diese benutzerdefinierten Attribute in der Antwort des Zugriffstokens angezeigt. Auch dies ist vielleicht nicht das gewünschte Verhalten.

Um benutzerdefinierte Attribute in diesen Fällen auszublenden, haben Sie folgende Möglichkeiten:

• Setzen Sie die benutzerdefinierten Attribute in der Richtlinie für das Aktualisierungstoken explizit zurück und setzen Sie ihre Anzeige auf "false". In diesem Fall müssen Sie unter Umständen die ursprünglichen benutzerdefinierten Werte aus dem ursprünglichen Zugriffstoken mit der Richtlinie "GetOAuthV2Info" abrufen.
• Verwenden Sie eine nachbearbeitete JavaScript-Richtlinie, um alle benutzerdefinierten Attribute manuell zu extrahieren, die in der Antwort nicht angezeigt werden sollen.

Siehe Token und Autorisierungscodes anpassen.

Default	N/A
Präsenz	Optional
Zulässige Werte	name - Der Name des Attributs ref – Der Wert des Attributs. Kann aus einer Ablaufvariable stammen. display (optional) Hiermit können Sie angeben, ob benutzerdefinierte Attribute in der Antwort angezeigt werden sollen. Bei true werden benutzerdefinierte Attribute in der Antwort angezeigt (wenn GenerateResponse ebenfalls aktiviert ist). Ist false aktiviert, werden benutzerdefinierte Attribute nicht in die Antwort aufgenommen. Der Standardwert ist true. Weitere Informationen finden Sie unter Benutzerdefinierte Attribute in der Antwort anzeigen oder ausblenden.
Wird mit Berechtigungstypen verwendet	authorization_code implizit Passwort client_credentials refresh_token Kann auch mit dem GenerateAuthorizationCode-Vorgang verwendet werden.

<CacheExpiryInSeconds> Element

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

Dieses Element kann nur mit dem Vorgang VerifyAccessToken verwendet werden. Sie gibt die Gültigkeitsdauer (Time-to-Live, TTL) für den Zugriffstoken-Cache für die jeweilige Richtlinienausführung an. Wenn Apigee zum ersten Mal ein OAuth 2-Zugriffstoken verifiziert, muss es das Zugriffstoken aus einem persistenten Speicher abrufen. Dies ist ein relativ aufwendiger Vorgang. Daher speichert Apigee das Ergebnis der Tokensuche im Cache, einschließlich des Tokenstatus, der Liste der Produkte, für die das Token gültig ist, und aller benutzerdefinierten Attribute, die dem Token zugeordnet sind. Bei nachfolgenden Aufrufen von OAuthV2/VerifyAccessToken bis zum Ablauf der TTL wird das im Arbeitsspeicher zwischengespeicherte Ergebnis gelesen, was bedeutet, dass die Tokenüberprüfung viel schneller erfolgt.

Die Standard-TTL für den Zugriffstoken-Cache beträgt 180 Sekunden. Mit diesem Element können Sie die TTL verkürzen und so die Leistung gegen die Richtigkeit eintauschen. Ein Szenario, in dem dies sinnvoll wäre, ist, wenn Sie manchmal Tokens widerrufen und den Zeitraum verkürzen möchten, in dem Apigee widerrufene Tokens weiterhin als gültig behandelt.

Der unterstützte Bereich liegt zwischen 1 und 180 Sekunden. Sie können eine Ablaufvariable und einen Standardwert angeben. Wenn Sie eine Ablaufvariable angeben und diese einen numerischen Wert enthält, hat sie Vorrang vor dem angegebenen Standardwert.

Hinweis: Wenn Sie eine niedrigere Zahl für den Cacheablauf verwenden, sinkt die Leistung.

Default	– Wenn Sie dieses Element weglassen, beträgt der Standardablaufzeitraum für das im Cache gespeicherte Zugriffstoken 180 Sekunden.
Präsenz	Optional
Typ	Ganzzahl
Zulässige Werte	Alle positiven, Ganzzahlen, die nicht Null sind. Gibt die Ablaufzeit in Sekunden an.
Wird bei Vorgängen verwendet	VerifyAccessToken

Attribute

In der folgenden Tabelle werden die Attribute des Elements <CacheExpiryInSeconds> beschrieben.

Attribut	Beschreibung	Standard	Präsenz
ref	Ein Verweis auf die Ablaufvariable mit dem Wert für den Cache-Ablauf, ausgedrückt in Sekunden. Wenn angegeben, hat der Ablaufvariablenwert Vorrang vor dem angegebenen Standardwert.	–	Optional

<ClientId>-Element

<ClientId>request.formparam.client_id</ClientId>

In einigen Fällen muss die Clientanwendung die Client-ID an den Autorisierungsserver senden. Mit diesem Element wird angegeben, dass Apigee in der Ablaufvariablen request.formparam.client_id nach der Client-ID suchen soll. Die Festlegung von ClientId auf eine andere Variable wird nicht unterstützt. Siehe auch OAuth 2.0-Tokens abrufen.

Default	request.formparam.client_id (eine x-www-form-urlencoded und im Anfragetext angegeben)
Präsenz	Optional
Typ	String
Zulässige Werte	Die Ablaufvariable: request.formparam.client_id
Wird mit Berechtigungstypen verwendet	authorization_code Passwort implizit client_credentials Kann auch mit dem GenerateAuthorizationCode-Vorgang verwendet werden.

<Code>-Element

<Code>request.queryparam.code</Code>

Im Autorisierungsablauf der Autorisierung muss der Client einen Autorisierungscode an den Autorisierungsserver (Apigee) senden. Mit diesem Element können Sie angeben, wo Apigee nach dem Autorisierungscode suchen soll. Dieser kann beispielsweise als Abfrageparameter, HTTP-Header oder Formularparameter (Standard) gesendet werden.

Die Variable request.queryparam.auth_code gibt an, dass der Autorisierungscode als Abfrageparameter vorhanden sein soll, z. B. ?auth_code=AfGlvs9. Wenn der Autorisierungscode in einem HTTP-Header erforderlich sein soll, legen Sie beispielsweise diesen Wert auf request.header.auth_code fest. Weitere Informationen finden Sie unter OAuth 2.0-Tokens abrufen.

Default	request.formparam.code (eine x-www-form-urlencoded und im Anfragetext angegeben)
Präsenz	optional
Typ	String
Zulässige Werte	Jede Ablaufvariable, auf die die Richtlinie zur Laufzeit zugreifen kann
Wird mit Berechtigungstypen verwendet	authorization_code

<ExpiresIn>-Element

<ExpiresIn>10000</ExpiresIn>

Erzwingt die Ablaufzeit von Zugriffstoken und Autorisierungscodes in Millisekunden. Verwenden Sie <RefreshTokenExpiresIn> für Aktualisierungstokens. Der Ablaufzeitpunkt ist ein vom System generierter Wert plus dem Wert <ExpiresIn>. Wenn <ExpiresIn> nicht angegeben ist, wendet das System einen auf Systemebene konfigurierten Standardwert an.

Die Ablaufzeit kann auch zur Laufzeit entweder mit einem hartcodierten Standardwert oder durch Verweis auf eine Ablaufvariable festgelegt werden. Sie können z. B. einen Tokenablaufwert in einer Schlüsselwertzuordnung speichern, ihn abrufen, einer Variable zuweisen und in der Richtlinie darauf verweisen. Beispiel: kvm.oauth.expires_in.

Apigee speichert die folgenden Entitäten für mindestens 180 Sekunden im Cache, nachdem die Entitäten aufgerufen wurden.

• OAuth Zugriffstoken Das bedeutet, das Element ExpiresIn in der OAuth v2-Richtlinie kann ein Zugriffstoken nicht in weniger als 180 Sekunden entwerten.
• KMS-Entitäten (Key Management Service, Anwendungen, Entwickler, API-Produkte)
• Benutzerdefinierte Attribute für OAuth-Tokens und KMS-Entitäten.

Im folgenden Stanza wird auch eine Ablaufvariable und ein Standardwert angegeben. Der Wert der Ablaufvariable hat Vorrang vor dem angegebenen Standardwert.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee unterstützt keine Möglichkeit, das Ablaufdatum eines Tokens zu erzwingen, nachdem es erstellt wurde. Wenn Sie den Ablauf von Tokens erzwingen müssen (z. B. auf einer Bedingung), ist eine Lösung in diesem Apigee Community-Post beschrieben.

Standardmäßig werden abgelaufene Zugriffstokens 3 Tage nach Ablauf automatisch aus dem Apigee-System entfernt. Weitere Informationen finden Sie unter Zugriffstokens bereinigen.

Default	Wenn keine Angabe erfolgt, wendet das System einen auf Systemebene konfigurierten Standardwert an.
Präsenz	Optional
Typ	Ganzzahl
Zulässige Werte	Alle positiven Ganzzahlen, die nicht Null sind. Geben Sie die Ablaufzeit in Millisekunden an. Obwohl der Wert dieses Elements in Millisekunden angegeben wird, wird der Wert, der im Attribut expires_in des Tokens und in der Ablaufvariable expires_in festgelegt ist, in Sekunden ausgedrückt.
Wird mit Berechtigungstypen verwendet	authorization_code implizit Passwort client_credentials refresh_token Wird auch mit dem GenerateAuthorizationCode-Vorgang verwendet.

<ExternalAccessToken>-Element

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Teilt Apigee mit, wo ein externes Zugriffstoken zu finden ist (ein Zugriffstoken, das nicht von Apigee generiert wird).

Die Variable request.queryparam.external_access_token gibt an, dass das externe Zugriffstoken als Abfrageparameter vorhanden sein soll, z. B. ?external_access_token=12345678. Wenn Sie beispielsweise das externe Zugriffstoken in einem HTTP-Header anfordern möchten, legen Sie diesen Wert auf request.header.external_access_token fest. Siehe auch OAuth-Token von Drittanbietern verwenden.

<ExternalAuthorization>-Element

<ExternalAuthorization>true</ExternalAuthorization>

Wenn dieses Element falsch oder nicht vorhanden ist, validiert Apigee die Client-ID und den Clientschlüssel normalerweise anhand des Apigee-Autorisierungsspeichers. Verwenden Sie dieses Element, wenn Sie mit OAuth-Tokens von Drittanbietern arbeiten möchten. Weitere Informationen zur Verwendung dieses Elements finden Sie unter OAuth-Token von Drittanbietern verwenden.

Default	false
Präsenz	Optional
Typ	Boolesch
Zulässige Werte	"true" oder "false"
Wird mit Berechtigungstypen verwendet	authorization_code Passwort client_credentials

{ExternalAuthorizationCode} -Element

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Gibt Apigee an, wo ein externer Authentifizierungscode zu finden ist (ein nicht von Apigee generierter Autorisierungscode).

Die Variable request.queryparam.external_auth_code gibt an, dass der externe Authentifizierungscode als Abfrageparameter vorhanden sein soll, z. B. ?external_auth_code=12345678. Wenn Sie beispielsweise den externen Authentifizierungscode in einem HTTP-Header benötigen, legen Sie diesen Wert auf request.header.external_auth_code fest. Siehe auch OAuth-Token von Drittanbietern verwenden.

<ExternalRefreshToken>-Element

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Teilt Apigee mit, wo ein externes Aktualisierungstoken zu finden ist (ein Aktualisierungstoken, das nicht von Apigee generiert wurde).

Die Variable request.queryparam.external_refresh_token gibt an, dass das externe Aktualisierungstoken als Abfrageparameter vorhanden sein soll, z. B. ?external_refresh_token=12345678. Wenn Sie beispielsweise das externe Aktualisierungstoken in einem HTTP-Header benötigen, legen Sie diesen Wert auf request.header.external_refresh_token fest. Siehe auch OAuth-Token von Drittanbietern verwenden.

{GenerateResponse}-Element

<GenerateResponse enabled='true'/>

Wenn der Wert auf true gesetzt ist oder wenn das Attribut enabled weggelassen wird, generiert die Richtlinie eine Antwort und gibt diese zurück. Für GenerateAccessToken kann die Antwort beispielsweise so aussehen:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "[e-mail]",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Wenn false festgelegt ist oder das <GenerateResponse>-Element weggelassen wird, wird keine Antwort gesendet. Stattdessen enthält eine Reihe von Ablaufvariablen Werte, die sich auf die Richtlinienfunktion beziehen. Beispiel: Eine Ablaufvariable mit dem Namen oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code wird mit dem neu ausgefüllten Authentifizierungscode gefüllt. Beachten Sie, dass expires_in in der Antwort in Sekunden angegeben wird.

Default	wahr
Präsenz	Optional
Typ	String
Zulässige Werte	"true" oder "false"
Wird mit Berechtigungstypen verwendet	implizit Passwort client_credentials refresh_token Kann auch mit dem GenerateAuthorizationCode-Vorgang verwendet werden.

<GenerateErrorResponse>-Element

<GenerateErrorResponse enabled='true'/>

Bei Festlegung auf true generiert die Richtlinie eine Antwort und gibt sie zurück, wenn das ContinueOnError-Attribut auf "true" gesetzt ist. Bei false (Standardeinstellung), wird keine Antwort gesendet. Stattdessen enthält eine Reihe von Ablaufvariablen Werte, die sich auf die Richtlinienfunktion beziehen.

Default	false
Präsenz	Optional
Typ	String
Zulässige Werte	"true" oder "false"
Wird mit Berechtigungstypen verwendet	implizit Passwort client_credentials refresh_token Kann auch mit dem GenerateAuthorizationCode-Vorgang verwendet werden.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Gibt für die Richtlinie den Parameter für den Berechtigungstyp an, der in einer Anfrage übergeben wird. Gemäß OAuth 2.0-Spezifikation muss der Berechtigungstyp mit Anfragen für Zugriffstoken und Autorisierungscodes angegeben werden. Die Variable kann ein Header, ein Abfrageparameter oder ein Formularparameter (Standard) sein.

Beispiel: request.queryparam.grant_type gibt an, dass das Passwort als Abfrageparameter vorhanden sein soll, z. B. ?grant_type=password. Wenn Sie den Berechtigungstyp in einem HTTP-Header anfordern möchten, beispielsweise diesen Wert auf request.header.grant_type. Siehe auch OAuth 2.0-Tokens abrufen.

Default	request.formparam.grant_type (ein x-www-form-urlencoding, der im Anfragetext angegeben ist)
Präsenz	Optional
Typ	String
Zulässige Werte	Eine Variable, wie oben beschrieben.
Wird mit Berechtigungstypen verwendet	authorization_code Passwort implizit client_credentials refresh_token

<Operation>-Element

<Operation>GenerateAuthorizationCode</Operation>

Der OAuth 2.0-Vorgang, der von der Richtlinie ausgeführt wird.

Default	Wenn <Operation> nicht angegeben ist, prüft Apigee die Liste von <SupportedGrantTypes>. Nur Vorgänge für diese Berechtigungstypen werden erfolgreich ausgeführt. Mit anderen Worten: Sie können <Operation> weglassen, wenn Sie in der Liste <SupportedGrantTypes> eine <GrantType> angeben. Wenn weder <Operation> noch <SupportedGrantTypes> angegeben ist, lautet der Standardberechtigungstyp "authorization_code". Das heißt, der Autorisierungstyp "authorization_code" wird erfolgreich sein, alle anderen schlagen jedoch fehl.
Präsenz	Optional
Typ	String
Zulässige Werte	GenerateAccessToken: Generiert ein Zugriffstoken. Siehe auch OAuth 2.0-Tokens abrufen. GenerateAccessTokenImplicitGrant: Generiert ein Zugriffstoken für den impliziten Berechtigungstyp. Siehe auch OAuth 2.0-Tokens abrufen. GenerateAuthorizationCode: Generiert einen Authentifizierungscode. Wird mit dem Autorisierungcodetyp verwendet. Siehe auch OAuth 2.0-Tokens abrufen. RefreshAccessToken: Tauschen Sie es ein neues Zugriffstoken aus. Siehe auch OAuth 2.0-Tokens abrufen. VerifyAccessToken – Überprüft, ob ein in einer Anfrage gesendetes Zugriffstoken gültig ist. Weitere Informationen finden Sie oben im Beispiel "VerifyAccessToken" und unter Zugriffstoken prüfen. InvalidateToken - widerruft ein Zugriffstoken. Nachdem ein Token widerrufen wurde, können Clients dieses Token nicht mehr zum Aufrufen einer geschützten API verwenden. Siehe auch Zugriffstokens genehmigen und widerrufen. Warnung: OAuth-Tokens werden drei Minuten (180 Sekunden) im Cache gespeichert. Daher kann ein widerrufenes Token noch bis zu drei Minuten lang erfolgreich sein, bis sein Cache-Limit abläuft. ValidateToken – Erstellt oder genehmigt ein Zugriffstoken, das zuvor widerrufen wurde. Siehe auch Zugriffstokens genehmigen und widerrufen. Zusätzliche Vorgänge für JWT-Zugriffstokens Wenn Sie lieber JWT-Zugriffstokens anstelle von intransparenten Stringtokens verwenden möchten, stehen die folgenden Vorgänge auch zum Generieren und Prüfen von JWT-Tokens zur Verfügung. Einzelheiten finden Sie unter Vorgänge für JWT-OAuth-Tokens verwenden: GenerateJWTAccessToken: Generiert ein Zugriffstoken mit einem signierten JWT. Siehe JWT-Zugriffstoken generieren. GenerateJWTAccessTokenImplicitGrant: Generiert ein Zugriffstoken mit einem signierten JWT für den impliziten Berechtigungstyp. Siehe JWT-Zugriffstoken generieren. VerifyJWTAccessToken: Verifiziert ein signiertes JWT-Zugriffstoken. Siehe auch JWT-Zugriffstoken überprüfen. RefreshJWTAccessToken: Tauschen Sie ein Aktualisierungstoken für ein neues JWT-Zugriffstoken aus. Siehe auch JWT-Zugriffstoken aktualisieren.

<PassWord>-Element

<PassWord>request.queryparam.password</PassWord>

Dieses Element wird nur mit dem Typ der Passworterteilung verwendet. Bei der Passwortzuteilung müssen Nutzeranmeldedaten (Passwort und Nutzername) für die OAuthV2-Richtlinie verfügbar gemacht werden. Die Elemente <PassWord> und <UserName> werden verwendet, um Variablen anzugeben, unter denen Apigee diese Werte finden kann. Wenn diese Elemente nicht angegeben sind, erwartet die Richtlinie voraussichtlich die Werte (Standard) in den Formularparametern username und password. Wenn die Werte nicht gefunden werden, gibt die Richtlinie einen Fehler aus. Sie können die Elemente <PassWord> und <UserName> verwenden, um auf eine beliebige Ablaufvariable mit den Anmeldedaten zu verweisen.

Sie können das Passwort beispielsweise in einer Tokenanfrage mit einem Abfrageparameter übergeben und das Element so festlegen: <PassWord>request.queryparam.password</PassWord>. Um das Passwort in einem HTTP-Header anzugeben, legen Sie diesen Wert auf request.header.password fest.

Die OAuthV2-Richtlinie führt mit diesen Anmeldedaten keine weiteren Schritte aus. Apigee überprüft lediglich, ob sie vorhanden sind. Der API-Entwickler ruft die Werteanfrage ab und sendet sie vor der Ausführung der Richtlinie zur Tokengenerierung an einen Identitätsanbieter.

Siehe auch OAuth 2.0-Tokens abrufen.

Default	request.formparam.password (ein x-www-form-urlencoded und im Request-Text angegeben)
Präsenz	Optional
Typ	String
Zulässige Werte	Jede Ablaufvariable, die während Laufzeit für die Richtlinie verfügbar ist.
Wird mit Berechtigungstypen verwendet	Passwort

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

Stellt den privaten Schlüssel bereit, mit dem JWT-formatierte Zugriffstokens mit einem RSA-Algorithmus verifiziert oder signiert werden. Verwenden Sie das Attribut ref, um den Schlüssel in einer Ablaufvariable zu übergeben. Nur verwenden, wenn der Wert des Algorithm-Elements entweder RS256, RS384 oder RS512 ist. Weitere Informationen finden Sie unter Vorgänge für JWT-OAuth-Tokens verwenden.

Hinweis: Zum Schutz von Secrets hat es sich als Best Practice bewährt, den Schlüssel in einem umgebungsbezogenen Attributsatz oder einer umgebungsbezogenen Schlüssel/Wert-Zuordnung (key value map, KVM) zu speichern. Siehe auch Auf Attributsatzwerte zugreifen und Schlüssel/Wert-Zuordnungen verwenden..

Standard	–
Präsenz	Erforderlich, wenn der Wert des Algorithm-Elements HS256, HS384 oder HS512 ist.
Typ	String
Zulässige Werte	Eine Ablaufvariable mit einem String, der einen privaten PEM-codierten RSA-Schlüsselwert darstellt.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

Gibt den öffentlichen Schlüssel oder das öffentliche Zertifikat an, mit dem die Signatur auf einem JWT-formatierten Zugriffstoken verifiziert wird, das mit einem RSA-Algorithmus signiert ist. Verwenden Sie das Attribut ref, um den Schlüssel bzw. das Zertifikat in einer Ablaufvariable zu übergeben. Nur verwenden, wenn der Wert des Algorithm-Elements entweder RS256, RS384 oder RS512 ist.

Standard	–
Präsenz	Zum Verifizieren eines mit einem RSA-Algorithmus signierten JWT müssen Sie das Element "Certificate", "JWKS" oder "Value" verwenden.
Typ	String
Zulässige Werte	Eine Ablaufvariable oder ein String.

<RedirectUri> -Element

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Gibt an, wo Apigee in der Anfrage nach dem Parameter redirect_uri suchen soll.

Informationen zu Weiterleitungs-URIs

Weiterleitungs-URIs werden mit dem Autorisierungscode und den impliziten Berechtigungstypen verwendet. Der Weiterleitungs-URI teilt dem Autorisierungsserver (Apigee) mit, dass ein Autorisierungscode (für den Berechtigungstyp "auth") oder ein Zugriffstoken (für den impliziten Berechtigungstyp) gesendet werden soll. Es ist wichtig zu wissen, wann dieser Parameter erforderlich ist, wann er optional ist und wie er verwendet wird:

• (erforderlich) Wenn in der Entwickleranwendung eine Callback-URL registriert ist, die den Clientschlüsseln der Anfrage zugeordnet ist und die redirect_uri in der Anfrage vorhanden ist, müssen die beiden genau übereinstimmen. Wenn sie nicht übereinstimmen, wird ein Fehler zurückgegeben. Informationen zum Registrieren von Entwickleranwendungen auf Apigee und zum Festlegen einer Callback-URL finden Sie unter Anwendungen registrieren und API-Schlüssel verwalten.

  Hinweis: Um sicherzustellen, dass Apigee eine exakte Übereinstimmung zwischen "Callback URL" und "redirect_uri" (statt einer Weiterleitungsübereinstimmung) sucht, legen Sie das folgende Attribut in Ihrer Organisation fest: features.isStrictOAuthUriValidation = true. Der Standardwert ist "false" (Forward-Übereinstimmung).

  Wenden Sie sich an Google Cloud Customer Care, um das Attribut zu aktivieren.

• (optional) Wenn eine Callback-URL registriert ist und redirect_uri in der Anfrage fehlt, leitet Apigee an die registrierte Callback-URL weiter.
• (erforderlich) Wenn eine Callback-URL nicht registriert ist, ist redirect_uri erforderlich. Beachten Sie, dass Apigee in diesem Fall jede beliebige URL akzeptiert. Dieser Fall kann ein Sicherheitsproblem darstellen und sollte daher nur mit vertrauenswürdigen Client-Anwendungen verwendet werden. Wenn Clientanwendungen nicht vertrauenswürdig sind, empfiehlt es sich, immer eine Callback-URL zu registrieren.

Sie können diesen Parameter in einem Abfrageparameter oder in einem Header senden. Die Variable request.queryparam.redirect_uri gibt an, dass der Weiterleitungs-URI als Abfrageparameter vorhanden sein muss, z. B. ?redirect_uri=login.myapp.com. Um den Weiterleitungs-URI in einem HTTP-Header anzufordern, setzen Sie diesen Wert beispielsweise auf request.header.redirect_uri. Siehe auch OAuth 2.0-Tokens abrufen.

Default	request.formparam.redirect_uri (ein x-www-form-urlencoded und im Anfragetext)
Präsenz	Optional
Typ	String
Zulässige Werte	Jede Ablaufvariable, auf die während Laufzeit in der Richtlinie zugegriffen werden kann
Wird mit Berechtigungstypen verwendet	authorization_code implizit Wird ebenfalls mit dem GenerateAuthorizationCode-Vorgang verwendet.

<RefreshToken>-Element

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Wenn Sie ein Zugriffstoken mit einem Aktualisierungstoken anfordern, müssen Sie das Aktualisierungstoken in der Anfrage angeben. Mit diesem Element können Sie angeben, wo Apigee nach dem Aktualisierungstoken suchen soll. Sie kann beispielsweise als Abfrageparameter, HTTP-Header oder Formularparameter (Standardeinstellung) gesendet werden.

Die Variable request.queryparam.refreshtoken gibt an, dass das Aktualisierungstoken als Abfrageparameter vorhanden sein muss, z. B. ?refresh_token=login.myapp.com. Wenn Sie beispielsweise das Aktualisierungstoken in einem HTTP-Header benötigen, legen Sie diesen Wert auf request.header.refresh_token fest. Siehe auch OAuth 2.0-Tokens abrufen.

Default	request.formparam.refresh_token (x-www-form-urlencoded und im Anfragetext angegeben)
Präsenz	Optional
Typ	String
Zulässige Werte	Jede Ablaufvariable, auf die während Laufzeit in der Richtlinie zugegriffen werden kann
Wird mit Berechtigungstypen verwendet	refresh_token

<RefreshTokenExpiresIn>-Element

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Erzwingt die Ablaufzeit der Aktualisierungstokens in Millisekunden. Der Wert für die Ablaufzeit ist ein vom System generierter Wert plus der Wert <RefreshTokenExpiresIn>. Wenn <RefreshTokenExpiresIn> nicht angegeben ist, wendet das System den Standardwert an.

Die Ablaufzeit kann auch zur Laufzeit entweder mit einem hartcodierten Standardwert oder durch Verweis auf eine Ablaufvariable festgelegt werden. Sie können z. B. einen Tokenablaufwert in einer Schlüsselwertzuordnung speichern, ihn abrufen, einer Variable zuweisen und in der Richtlinie darauf verweisen. Beispiel: kvm.oauth.expires_in

Im folgenden Stanza wird auch eine Ablaufvariable und ein Standardwert angegeben. Der Wert der Ablaufvariable hat Vorrang vor dem angegebenen Standardwert.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

Default	2592000000 ms (30 Tage) (gültig ab dem 31. Mai 2023)
Präsenz	Optional
Typ	Ganzzahl
Zulässige Werte	Alle positiven Ganzzahlen, die nicht Null sind. Gibt die Ablaufzeit in Millisekunden an.
Wird mit Berechtigungstypen verwendet	authorization_code Passwort refresh_token

<ResponseType>-Element

<ResponseType>request.queryparam.response_type</ResponseType>

Dieses Element teilt Apigee mit, welche Art von Clientanwendung angefordert wird. Sie wird nur mit dem Autorisierungscode und den impliziten Berechtigungstypen verwendet.

Standardmäßig sucht Apigee in dem Abfrageparameter response_type nach dem Antworttypwert. Wenn Sie dieses Standardverhalten überschreiben möchten, konfigurieren Sie mit dem <ResponseType>-Element eine Ablaufvariable, die den Antworttypwert enthält. Wenn Sie dieses Element beispielsweise auf request.header.response_type festlegen, sucht Apigee nach dem Antworttyp, der im Anfrage-Header übergeben wird. Siehe auch OAuth 2.0-Tokens abrufen.

Default	request.formparam.response_type (ein x-www-form-urlencoded und im Anfragetext angegeben)
Präsenz	Optional. Verwenden Sie dieses Element, wenn Sie das Standardverhalten überschreiben möchten.
Typ	String
Zulässige Werte	Entweder code (für den Autorisierungscode-Typ) oder token (für den impliziten Berechtigungstyp)
Wird mit Berechtigungstypen verwendet	implizit Wird ebenfalls mit dem GenerateAuthorizationCode-Vorgang verwendet.

<ReuseRefreshToken> -Element

<ReuseRefreshToken>true</ReuseRefreshToken>

Bei der Einstellung true wird das vorhandene Aktualisierungstoken wiederverwendet, bis es abläuft. Bei false, wird von Apigee ein neues Aktualisierungstoken ausgegeben, wenn ein gültiges Aktualisierungstoken angezeigt wird.

Default	false
Präsenz	optional
Typ	boolean
Zulässige Werte	true oder false
Wird mit Berechtigungstypen verwendet	refresh_token

<RFCCompliantRequestResponse>-Element

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

Die OAuthV2-Richtlinie mit dem Vorgang „GenerateAccessToken“ kann eine Antwort zurückgeben, die nicht den zugehörigen IETF OAuth 2.0-Spezifikationen entspricht, einschließlich RFC 6749 und RFC 6750. Wenn Sie das Element RFCCompliantRequestResponse mit dem Wert true in Ihre Richtlinie einfügen, gibt die OAuthV2-Richtlinie eine RFC-konforme Antwort zurück.

In der folgenden Tabelle sind die Unterschiede bei einigen Werten aufgeführt, die von der OAuthV2-Richtlinie zurückgegeben werden, je nachdem, ob das Element RFCCompliantRequestResponse true oder false ist.

Element	Der Wert ist „false“ oder fehlt.	Wert ist „true“
Cache-Control-HTTP-Header	Nicht angegeben	Fehler- und Nicht-Fehlerantworten enthalten das HTTP-Antwortheaderfeld „Cache-Control“, um RFC2616 (Hypertext Transfer Protocol – HTTP/1.1) zu entsprechen. Der Wert ist no-store in allen Antworten, die Tokens, Anmeldedaten oder andere vertrauliche Informationen enthalten, sowie das Antwortheaderfeld Pragma mit dem Wert no-cache.
Attribut "token_type" in einer gültigen Tokenantwort	Ein nicht konformer token_type-Wert. { ... "token_type": "BearerToken", ... }	Ein konformer token_type-Wert. { ... "token_type": "Bearer", ... }
Attribute "expires_in" und "refresh_token_expires_in" in einer gültigen Tokenantwort	Der numerische Wert ist in Anführungszeichen gesetzt. Beispiel: { ... "expires_in": "3600", "refresh_token_expires_in": "345600", ... }	Der Wert wird als Zahl und nicht als String serialisiert. Beispiel: { ... "expires_in": 3600, "refresh_token_expires_in": 345600, ... }
Fehlerantwort für ein abgelaufenes Aktualisierungstoken, wenn grant_type = refresh_token	Fehlerantworten entsprachen nicht RFC 6749. Beispiel: { "ErrorCode": "InvalidRequest", "Error": "Refresh Token expired" }	Nutzlasten für Fehlerantworten enthalten die Elemente "error" und "error_description". Beispiel: { "error": "invalid_grant", "error_description": "refresh token expired" }

Hinweis : Die Antwort von Apigee enthält einige Attribute, die nicht explizit in RFC 6749 erwähnt werden. Die Spezifikation erlaubt zusätzliche Attribute. Wenn Sie die Antwort so anpassen möchten, dass sie nur die benötigten Eigenschaften enthält, verwenden Sie das Element GenerateResponseElement, das auf false festgelegt ist, und verwenden Sie dann eine AssignMessage- oder JavaScript-Richtlinie, um Ihre eigene Antwortnutzlast zu erstellen.

Default	false: Standardmäßig weist die Richtlinie bestimmte nicht RFC-kompatible Verhaltensweisen auf, wie oben beschrieben.
Präsenz	Optional
Typ	Boolesch
Zulässige Werte	true oder false
Wird mit Berechtigungstypen verwendet	Alle

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

Stellt den geheimen Schlüssel bereit, mit dem JWT-formatierte Zugriffstokens mit einem HMAC-Algorithmus verifiziert oder signiert werden. Nur verwenden, wenn der Algorithmus HS256, HS384 oder HS512 ist. Verwenden Sie das Attribut ref, um den Schlüssel in einer Ablaufvariable zu übergeben. Weitere Informationen finden Sie unter Vorgänge für JWT-OAuth-Tokens verwenden.

Apigee erzwingt eine Mindestschlüsselstärke für die Algorithmen HS256/HS384/HS512. Die Mindestschlüssellänge für HS256 beträgt 32 Byte, für HS384 48 Byte und für HS512 64 Byte. Die Verwendung eines Schlüssels mit geringerer Stärke führt zu einem Laufzeitfehler.

Hinweis: Zum Schutz von Secrets hat es sich als Best Practice bewährt, den Schlüssel in einem umgebungsbezogenen Attributsatz oder einer umgebungsbezogenen Schlüssel/Wert-Zuordnung (key value map, KVM) zu speichern. Siehe auch Auf Attributsatzwerte zugreifen und Schlüssel/Wert-Zuordnungen verwenden..

Standard	–
Präsenz	Erforderlich für HMAC-Algorithmen.
Typ	String
Zulässige Werte	Eine Ablaufvariable

<Scope>-Element

<Scope>request.queryparam.scope</Scope>

Wenn dieses Element in einer der GenerateAccessToken- oder GenerateAuthorizationCode-Richtlinien enthalten ist, wird damit angegeben, welche Bereiche dem Token oder Code gewährt werden sollen. Diese Werte werden normalerweise in der Anfrage von einer Clientanwendung an die Richtlinie übergeben. Sie können das Element so konfigurieren, dass eine Ablaufvariable verwendet wird. So können Sie auswählen, wie die Bereiche in einer Anfrage übergeben werden. Im folgenden Beispiel gibt request.queryparam.scope an, dass der Bereich als Abfrageparameter vorhanden ist, z. B. ?scope=READ. Wenn Sie beispielsweise den Bereich in einem HTTP-Header benötigen, legen Sie diesen Wert auf request.header.scope fest.

Wenn dieses Element in einer Richtlinie "VerifyAccessToken" angezeigt wird, wird damit angegeben, welche Bereiche die Richtlinie erzwingen soll. Bei diesem Richtlinientyp muss der Wert ein "fest codierter" Bereichsname sein. Sie können keine Variablen verwenden. Beispiel:

<Scope>A B</Scope>

Weitere Informationen finden Sie unter Mit OAuth2-Bereichen arbeiten und OAuth 2.0-Tokens abrufen.

Default	Kein Bereich
Präsenz	Optional
Typ	String
Zulässige Werte	Bei Verwendung mit Generate*-Richtlinien eine Ablaufvariable. Bei Verwendung mit VerifyAccessToken eine durch Leerzeichen getrennte Liste mit Bereichsnamen (Strings).
Wird mit Berechtigungstypen verwendet	authorization_code implizit Passwort client_credentials Kann auch mit den GenerateAuthorizationCode- und VerifyAccessToken-Vorgängen verwendet werden.

<State>-Element

<State>request.queryparam.state</State>

Falls die Clientanwendung die Statusinformationen an den Autorisierungsserver senden muss, können Sie mit diesem Element angeben, wo Apigee nach den Statuswerten suchen soll. Sie kann beispielsweise als Abfrageparameter oder in einem HTTP-Header gesendet werden. Der Zustandswert wird in der Regel als Sicherheitsmaßnahme verwendet, um CSRF-Angriffe zu verhindern.

Der Status request.queryparam.state gibt beispielsweise an, dass der Status als Abfrageparameter vorhanden sein soll, z. B. ?state=HjoiuKJH32. Wenn Sie den Status beispielsweise in einem HTTP-Header angeben möchten, setzen Sie diesen Wert auf request.header.state. Siehe auch OAuth 2.0-Tokens abrufen.

Default	Kein Status
Präsenz	Optional
Typ	String
Zulässige Werte	Jede Ablaufvariable, auf die die Richtlinie zur Laufzeit zugreifen kann
Wird mit Berechtigungstypen verwendet	Alle Kann auch mit dem GenerateAuthorizationCode-Vorgang verwendet werden

<StoreToken>-Element

 <StoreToken>true</StoreToken>

Setzen Sie dieses Element auf true, wenn das <ExternalAuthorization>-Element true ist. Das Element <StoreToken> weist Apigee an, das externe Zugriffstoken zu speichern. Andernfalls wird es nicht beibehalten.

Default	false
Präsenz	Optional
Typ	Boolesch
Zulässige Werte	"true" oder "false"
Wird mit Berechtigungstypen verwendet	authorization_code Passwort client_credentials

<SupportedGrantTypes>/<GrantType>-Element

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Gibt die von einem OAuth-Tokenendpunkt auf Apigee unterstützten Berechtigungstypen an. Ein Endpunkt unterstützt möglicherweise mehrere Berechtigungstypen, d. h., es kann ein einzelner Endpunkt so konfiguriert werden, dass Zugriffstoken für mehrere Berechtigungstypen verteilt werden. Weitere Informationen zu Endpunkten finden Sie unter OAuth-Endpunkte. Der Berechtigungstyp wird in Tokenanfragen in einem grant_type - Parameter übergeben.

Wenn keine unterstützten Berechtigungstypen angegeben sind, sind nur die Typen authorization_code und implicit zulässig. Siehe auch das Element <GrantType>, das ein übergeordnetes Element ist, mit dem angegeben wird, wo Apigee nach dem Parameter grant_type sucht, der in einem Client übergeben wird Anfrage festgelegt werden. Apigee sorgt dafür, dass der Wert des Parameters grant_type mit einem der unterstützten Berechtigungstypen übereinstimmt.

Default	authorization _code und implizit
Präsenz	Erforderlich
Typ	String
Zulässige Werte	client_credentials authorization_code Passwort implizit

<Tokens>/<Token>-Element

Wird mit den ValidateToken- und InvalidateToken-Vorgängen verwendet. Siehe auch Zugriffstokens genehmigen und widerrufen. Das Element {Token} gibt die Ablaufvariable an, die die Quelle des zu widerrufenden Tokens definiert. Wenn Entwickler Zugriffstokens als Abfrageparameter mit dem Namen access_token senden möchten, verwenden Sie beispielsweise request.queryparam.access_token.

<UserName>-Element

<UserName>request.queryparam.user_name</UserName>

Dieses Element wird nur mit dem Typ der Passworterteilung verwendet. Bei der Passwortzuteilung müssen Nutzeranmeldedaten (Passwort und Nutzername) für die OAuthV2-Richtlinie verfügbar gemacht werden. Die Elemente <PassWord> und <UserName> werden verwendet, um Variablen anzugeben, unter denen Apigee diese Werte finden kann. Wenn diese Elemente nicht angegeben sind, erwartet die Richtlinie voraussichtlich die Werte (Standard) in den Formularparametern username und password. Wenn die Werte nicht gefunden werden, gibt die Richtlinie einen Fehler aus. Sie können die Elemente <PassWord> und <UserName> verwenden, um auf eine beliebige Ablaufvariable mit den Anmeldedaten zu verweisen.

Sie können beispielsweise den Nutzernamen in einem Abfrageparameter übergeben und das <UserName>-Element so festlegen: <UserName>request.queryparam.username</UserName>.Wenn der Nutzername in einem HTTP-Header erforderlich sein soll, legen Sie Folgendes fest: diesen Wert auf request.header.username.

Die OAuthV2-Richtlinie führt mit diesen Anmeldedaten keine weiteren Schritte aus. Apigee überprüft lediglich, ob sie vorhanden sind. Der API-Entwickler ruft die Werteanfrage ab und sendet sie vor der Ausführung der Richtlinie zur Tokengenerierung an einen Identitätsanbieter.

Siehe auch OAuth 2.0-Tokens abrufen.

Default	request.formparam.username (ein x-www-form-urlencoded und im Anfragetext angegeben)
Präsenz	Optional
Typ	String
Zulässige Werte	Beliebige Variableneinstellung.
Wird mit Berechtigungstypen verwendet	Passwort

Zugriffstoken prüfen

Sobald ein Tokenendpunkt für einen API-Proxy eingerichtet wurde, wird eine entsprechende OAuthV2-Richtlinie, die den Vorgang VerifyAccessToken angibt, an den Ablauf angehängt, der die geschützte Ressource verfügbar macht.

Die folgende Richtlinie erzwingt beispielsweise die Überprüfung des Zugriffstokens, um dafür zu sorgen, dass alle Anfragen an eine API autorisiert werden:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Die Richtlinie ist an die API-Ressource angehängt, die geschützt werden soll. Um sicherzustellen, dass alle Anfragen an eine API bestätigt werden, hängen Sie die Richtlinie an die ProxyEndpoint-Anfrage PreFlow an:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Mit den folgenden optionalen Elementen können die Standardeinstellungen für den Vorgang "VerifyAccessToken" überschrieben werden.

Name	Beschreibung
Umfang	Eine durch Leerzeichen getrennte Liste von Bereichen. Die Überprüfung ist erfolgreich, wenn mindestens ein aufgeführter Bereich im Zugriffstoken vorhanden ist. Die folgende Richtlinie überprüft beispielsweise das Zugriffstoken, um sicherzustellen, dass es mindestens einen der aufgeführten Bereiche enthält. Wenn READ oder WRITE vorhanden ist, ist die Bestätigung erfolgreich. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2>
AccessToken	Die Variable, in der sich das Zugriffstoken befinden soll. Beispiel: request.queryparam.accesstoken Standardmäßig wird das Zugriffstoken gemäß der OAuth 2.0-Spezifikation im Autorisierungs-HTTP-Header der Anwendung angezeigt. Verwenden Sie diese Einstellung, wenn ein Zugriffstoken an einem nicht standardmäßigen Speicherort erstellt werden soll, z. B. in einem Abfrageparameter oder in einem HTTP-Header mit einem anderen Namen als "Autorisierung".

Weitere Informationen finden Sie unter Zugriffstokens prüfen und OAuth 2.0-Tokens abrufen.

Speicherorte von Anfragevariablen festlegen

Für jeden Berechtigungstyp nimmt die Richtlinie Annahmen zum Standort oder zu erforderlichen Informationen in Anfragenachrichten vor. Diese Annahmen basieren auf der Spezifikation für OAuth 2.0. Wenn Ihre Anwendungen von der OAuth 2.0-Spezifikation abweichen müssen, können Sie die erwarteten Speicherorte für jeden Parameter angeben. Beispielsweise können Sie bei der Verarbeitung eines Autorisierungscodes den Speicherort des Autorisierungscodes, die Client-ID, den Weiterleitungs-URI und den Bereich angeben. Diese können als HTTP-Header, Abfrageparameter oder Formularparameter angegeben werden.

Das folgende Beispiel zeigt, wie Sie den Speicherort der erforderlichen Autorisierungscode-Parameter als HTTP-Header angeben können:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Bei Bedarf können Sie die Header und Abfrageparameter der Anwendung auch kombinieren, um Ihre Clientanwendungs-Basis zu unterstützen:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Pro Parameter kann nur ein Standort konfiguriert werden.

Ablaufvariablen

Die in dieser Tabelle definierten Ablaufvariablen werden beim Ausführen der entsprechenden OAuth-Richtlinien ausgefüllt und sind somit für andere Richtlinien oder Anwendungen verfügbar, die im API-Proxy-Ablauf ausgeführt werden.

Vorgang "VerifyAccessToken"

Wenn der Vorgang "VerifyAccessToken" ausgeführt wird, wird eine große Anzahl an Ablaufvariablen im Ausführungskontext des Proxys eingefügt. Mit diesen Variablen erhalten Sie Attribute, die sich auf das Zugriffstoken, die Entwickler-App und den Entwickler beziehen. Sie können beispielsweise AssignMessage- oder JavaScript-Richtlinien verwenden, um beispielsweise alle Variablen zu lesen und sie später im Ablauf zu verwenden. Diese Variablen können auch zur Fehlerbehebung nützlich sein.

Hinweis API-Produktvariablen werden automatisch ausgefüllt, wenn die API-Produkte mit einer gültigen Umgebung, Proxys und API-Ressourcen konfiguriert sind (von der proxy.pathsuffix). Die Variable "flow.resource.name" muss nicht explizit festgelegt werden.

Wenn die API-Produkte nicht mit gültigen Umgebungen und API-Proxys konfiguriert sind, muss flow.resource.name explizit so eingestellt werden, dass API-Produktvariablen im Ablauf ausgefüllt werden. Weitere Informationen zur Produktkonfiguration finden Sie unter API-Produkte verwalten.

Tokenspezifische Variablen

Variablen	Beschreibung
organization_name	Der Name der Organisation, in der der Proxy ausgeführt wird.
developer.id	Die ID des Entwicklers oder der AppGroup, die mit der registrierten Clientanwendung verknüpft ist.
developer.app.name	Der Name des Entwicklers oder der Anwendung AppGroup, der mit der registrierten Client-App verknüpft ist.
client_id	Die Client-ID der registrierten Clientanwendung.
grant_type	Die Art des Berechtigungstyps, die der Anfrage zugeordnet ist. Wird für den Vorgang VerifyJWTAccessToken nicht unterstützt.
token_type	Der Tokentyp, der der Anfrage zugeordnet ist.
access_token	Das Zugriffstoken, das verifiziert wird.
accesstoken.{custom_attribute}	Ein benanntes benutzerdefiniertes Attribut im Zugriffstoken.
issued_at	Das Datum, an dem das Zugriffstoken in Unix-Epochenzeit in Millisekunden ausgedrückt wurde.
expires_in	Die Ablaufzeit für das Zugriffstoken. Verfügbar in Sekunden. Obwohl mit dem Element ExpiresIn die Ablaufzeit in Millisekunden festgelegt wird, wird der Wert in der Tokenantwort und den Ablaufvariablen in Sekunden ausgegeben.
status	Der Status des Zugriffstokens (z.B. genehmigt oder widerrufen).
scope	Der Bereich (falls vorhanden) des Zugriffstokens.
apiproduct.<custom_attribute_name>	Ein benanntes benutzerdefiniertes Attribut des API-Produkts, das der registrierten Clientanwendung zugeordnet ist.
apiproduct.name	Der Name des API-Produkts, das der registrierten Clientanwendung zugeordnet ist.
revoke_reason	(Nur Apigee-Hybrid) Gibt an, warum das Zugriffstoken widerrufen wurde. Wird für den Vorgang VerifyJWTAccessToken nicht unterstützt. Der Wert kann REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER oder TOKEN_REVOKED sein.

Anwendungsspezifische Variablen

Diese Variablen beziehen sich auf die Entwickleranwendung, die dem Token zugeordnet ist.

Variablen	Beschreibung
app.name
app.id
app.accessType
app.callbackUrl
app.status	Genehmigt oder widerrufen
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType	Beispiel: Entwickler
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes}	Ein benanntes benutzerdefiniertes Attribut der registrierten Clientanwendung.

AppGroup-spezifische Variablen

Die folgenden Ablaufvariablen mit Informationen zur AppGroup für das Token und werden von der Richtlinie ausgefüllt. Diese AppGroup-Attribute werden nur ausgefüllt, wenn verifyapikey.{policy_name}.app.appType "AppGroup" ist.

Hinweis:Wenn Sie von Apigee Edge migrieren, sind Ihre Unternehmensflussvariablen nach der Migration automatisch im entsprechenden AppGroup-Attribut verfügbar. Während der Migration sind keine Änderungen an den Bundles erforderlich.

Variablen	Beschreibung
appgroup.displayName	Der Anzeigename der AppGroup.
appgroup.name	Name der AppGroup.
appgroup.id	Die AppGroup-ID. Hinweis: Diese ID wird intern von Apigee generiert und es ist nicht sicher, dass sie im Laufe der Zeit gleich bleibt. Verwenden Sie die Variable appgroup.id nicht für folgende Zwecke: Kontingent-ID KVM-Schlüssel Kennungen, die an Ziele gesendet werden, um in der Backend-Geschäftslogik verwendet zu werden
appOwnerStatus	Der Status des App-Inhabers: "active", "inactive" oder "login_lock".
created_at	Das Datum/die Uhrzeit, zu der die AppGroup erstellt wurde.
created_by	Die E-Mail-Adresse des Entwicklers, der die AppGroup erstellt hat.
last_modified_at	Der Datums-/Zeitstempel, zu dem die AppGroup zuletzt geändert wurde.
last_modified_by	Die E-Mail-Adresse des Entwicklers, der die AppGroup zuletzt geändert hat.
{appgroup_custom_attributes}	Jedes benutzerdefinierte AppGroup-Attribut. Geben Sie den Namen des benutzerdefinierten Attributs an.

Entwicklerspezifische Variablen

Wenn app.appType "Developer" ist, werden Entwicklerattribute ausgefüllt.

Variablen	Beschreibung
Entwicklerspezifische Variablen
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status	"Aktiv" oder "Inaktiv"
developer.apps	Hinweis: Der Zugriff auf diese Variable führt zu einer hohen Latenz, wenn die Anzahl der Anwendungen größer als 10 ist.
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes}	Ein benanntes benutzerdefiniertes Attribut des Entwicklers.

GenerateAuthorizationCode-Vorgang

Diese Variablen werden festgelegt, wenn der GenerateAuthorizationCode-Vorgang erfolgreich ausgeführt wird:

Präfix oauthv2authcode.{policy_name}.{variable_name}

Beispiel: oauthv2authcode.GenerateCodePolicy.code

Variable	Beschreibung
code	Der Autorisierungscode, der bei der Ausführung der Richtlinie generiert wird.
redirect_uri	Der Weiterleitungs-URI, der der registrierten Clientanwendung zugeordnet ist.
scope	Der optionale OAuth-Bereich, der in der Clientanfrage übergeben wird.
client_id	Die Client-ID, die in der Clientanfrage übergeben wurde.

GenerateAccessToken- und RefreshAccessToken-Vorgänge

Diese Variablen werden festgelegt, wenn die Vorgänge GenerateAccessToken und RefreshAccessToken erfolgreich ausgeführt werden. Beachten Sie, dass die Aktualisierungstokenvariablen nicht für den Ablauf der Clientanmeldedaten-Zuweisung gelten.

Präfix oauthv2accesstoken.{policy_name}.{variable_name}

Beispiel: oauthv2accesstoken.GenerateTokenPolicy.access_token

Variablenname	Beschreibung
access_token	Das generierte Zugriffstoken.
client_id	Die Client-ID der mit diesem Token verknüpften Entwickleranwendung.
expires_in	Der Ablaufwert für das Token. Weitere Informationen finden Sie unter dem Element <ExpiresIn>. Beachten Sie, dass expires_in in der Antwort in Sekunden ausgedrückt wird.
scope	Liste der verfügbaren für das Token konfigurierten Bereiche. Mit OAuth2-Bereichen arbeiten
status	approved oder revoked.
token_type	BearerToken ist auf gesetzt.
developer.email	Die E-Mail-Adresse des registrierten Entwicklers, der Inhaber der mit dem Token verknüpften Entwickleranwendung ist.
organization_name	Die Organisation, in der der Proxy ausgeführt wird.
api_product_list	Eine Liste der Produkte, die der zugehörigen Entwickleranwendung des Tokens zugeordnet sind
refresh_count
refresh_token	Das generierte Aktualisierungstoken. Es werden keine Aktualisierungstokens für den Typ der Clientanmeldedaten generiert.
refresh_token_expires_in	Die Lebensdauer des Aktualisierungstokens in Sekunden.
refresh_token_issued_at	Dieser Zeitwert ist die Stringdarstellung der entsprechenden 32-Bit-Zeitstempelmenge. Beispiel: "Mittwoch, 21. August 2013 19:16:47 UTC" entspricht dem Zeitstempelwert von 1377112607413.
refresh_token_status	approved oder revoked.

GenerateAccessTokenImplicitGrant

Diese Variablen werden festgelegt, wenn der iGenerateAccessTokenImplicit-Vorgang für den impliziten Beretigungstypablauf erfolgreich ausgeführt wird.

Präfix oauthv2accesstoken.{policy_name}.{variable_name}

Beispiel: oauthv2accesstoken.RefreshTokenPolicy.access_token

Variable	Beschreibung
oauthv2accesstoken.access_token	Das Zugriffstoken, das beim Ausführen der Richtlinie generiert wird.
oauthv2accesstoken.{policy_name}.expires_in	Der Ablaufwert für das Token in Sekunden. Weitere Informationen finden Sie im Element <ExpiresIn>.

Fehlerreferenz

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Thrown by operations
steps.oauth.v2.access_token_expired	401	The access token is expired.	VerifyAccessToken InvalidateToken
steps.oauth.v2.access_token_not_approved	401	The access token was revoked.	VerifyAccessToken
steps.oauth.v2.apiproduct_doesnot_exist	401	The requested API product does not exist in any of the API products associated with the access token.	VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken	500	The policy expected to find an access token in a variable specified in the <AccessToken> element, but the variable could not be resolved.	GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode	500	The policy expected to find an authorization code in a variable specified in the <Code> element, but the variable could not be resolved.	GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId	500	The policy expected to find the Client ID in a variable specified in the <ClientId> element, but the variable could not be resolved.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken	500	The policy expected to find a refresh token in a variable specified in the <RefreshToken> element, but the variable could not be resolved.	RefreshAccessToken
steps.oauth.v2.FailedToResolveToken	500	The policy expected to find a token in a variable specified in the <Tokens> element, but the variable could not be resolved.	ValidateToken InvalidateToken
steps.oauth.v2.InsufficientScope	403	The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes.	VerifyAccessToken
steps.oauth.v2.invalid_client	401	This error name is returned when the <GenerateResponse> property of the policy is set to true and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header. Note: It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names.	GenerateAccessToken RefreshAccessToken
steps.oauth.v2.InvalidRequest	400	This error name is used for multiple different kinds of errors, typically for missing or incorrect parameters sent in the request. If <GenerateResponse> is set to false, use fault variables (described below) to retrieve details about the error, such as the fault name and cause.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
steps.oauth.v2.InvalidAccessToken	401	The authorization header does not have the word Bearer, which is required. For example: Authorization: Bearer your_access_token	VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	The currently executing API proxy or operation is not in the Product associated with the access token. Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Managing API products for details. See also Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for more guidance on causes for this error.	VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier	500	This error name is returned when the <GenerateResponse> property of the policy is set to false and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header. Note: It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names.	GenerateAccessToken RefreshAccessToken
steps.oauth.v2.InvalidParameter	500	The policy must specify either an access token or an authorization code, but not both.	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType	500	The <Tokens>/<Token> element requires you to specify the token type (for example, refreshtoken). If the client passes the wrong type, this error is thrown.	ValidateToken InvalidateToken
steps.oauth.v2.MissingParameter	500	The response type is token, but no grant types are specified.	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType	500	The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element). Note: There is currently a bug where unsupported grant type errors are not thrown correctly. If an unsupported grant type error occurs, the proxy does not enter the Error Flow, as expected.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken

JWT token-specific runtime errors

Runtime error codes and descriptions for JWT auth token flows depend on the OAuth2 flow context:

• If the flow context is token generation or refresh, see Error codes for JWT token generation and refresh flows below.
• For the token verification flow, see Error codes for token verification flows below.

Error codes for JWT token generation and refresh flows

For OAuth2 flows that generate or refresh JWT tokens, error responses adhere to the error responses specified in RFC6749. For details, see Section 5.2 Error Response.

Error codes for the token verification flow

The error codes listed in the following table apply to VerifyAccessToken operation only.

Fault code	HTTP status	Cause	Thrown by operations
oauth.v2.JWTSigningFailed	401	The policy was unable to sign the JWT.	GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm	401	This occurs when the algorithm is not present in the JWT access token or when the value is not supported.	GenerateJWTAccessToken VerifyJWTAccessToken
oauth.v2.InsufficientKeyLength	401	In Generation of JWT, for a key less than the minimum size for the HS384 or HS512 algorithms	GenerateJWTAccessToken VerifyJWTAccessToken
oauth.v2.JWTAlgorithmMismatch	401	The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.	VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed	401	The policy was unable to decode the JWT. The JWT is possibly corrupted.	VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT	401	Occurs when the required claims are not present in the Jwt Access token	VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature	401	This occurs when the signature of JWT access token could not be verified or when the signature is invalid.	VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader	401	Occurs when the JWT's type is not at+Jwt	VerifyJWTAccessToken

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
InvalidValueForExpiresIn	For the <ExpiresIn> element, valid values are positive integers.
InvalidValueForRefreshTokenExpiresIn	For the <RefreshTokenExpiresIn> element, valid values are positive integers.
InvalidGrantType	An invalid grant type is specified in the <SupportedGrantTypes> element. See the policy reference for a list of valid types.
ExpiresInNotApplicableForOperation	Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not.
RefreshTokenExpiresInNotApplicableForOperation	Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not.
GrantTypesNotApplicableForOperation	Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation.
OperationRequired	You must specify an operation in this policy using the <Operation> element. Note: If the <Operation> element is missing, the UI throws a schema validation error.
InvalidOperation	You must specify a valid operation in this policy using the <Operation> element. Note: If the <Operation> element is invalid, the UI throws a schema validation error.
TokenValueRequired	You must specify a token <Token> value in the <Tokens> element.

JWT token-specific deployment errors

These deployment errors are specific to policies that use JWT token operations.

Error name	Cause
InvalidValueForAlgorithm	The algorithm specified in the <Algorithm> element is not among the list of available algorithms or is not present.
MissingKeyConfiguration	The required <SecretKey>, <PrivateKey>, or <PublicKey> elements are missing, depending on which algorithm is used.
EmptyValueElementForKeyConfiguration	The required child element <Value> is not defined in the <PrivateKey>, <PublicKey>, or <SecretKey> elements
InvalidKeyConfiguration	The <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
EmptyRefAttributeForKeyconfiguration	The ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements is empty.
InvalidVariableNameForKey	The flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements does not contain the private prefix.

Fault variables

These variables are set when this policy triggers an error at runtime.

Note: You can use these variables to create Fault Rule conditions. These variables are populated when an error occurs if <GenerateResponse> is set to false. If <GenerateResponse> is true, the policy returns a response to the client immediately if an error occurs -- the error flow is skipped and these variables are not populated. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name = "InvalidRequest"
oauthV2.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GenerateAccesstoken.fault.name = InvalidRequest Note: For the VerifyAccessToken operation, the fault name includes this suffix: keymanagement.service For example: keymanagement.service.invalid_access_token
oauthV2.policy_name.fault.cause	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

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

Example fault rule

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Tokens in Storage sind gehasht

Wenn Sie Apigee Hybrid oder Apigee verwenden, werden die OAuthV2-Zugriffstokens und -Aktualisierungstokens standardmäßig verschlüsselt, wenn sie in der Cassandra-Laufzeit gespeichert werden. Durch Hashing wird verhindert, dass die Tokens genutzt werden, wenn die Datenbank manipuliert wurde.

Mit der standardmäßigen OAuth-Konfiguration arbeiten

Jede Organisation (auch eine kostenlose Organisation in Apigee) wird mit einem OAuth-Token-Endpunkt bereitgestellt. Der Endpunkt ist mit Richtlinien im API-Proxy oauth vorkonfiguriert. Sie können den Tokenendpunkt verwenden, sobald Sie ein Konto in Apigee erstellt haben. Weitere Informationen finden Sie unter Informationen zu OAuth-Endpunkten.

Zugriffstokens löschen

OAuth2-Tokens werden standardmäßig drei Tage (259.200 Sekunden) aus dem Apigee-System gelöscht, nachdem das Zugriffstoken und das Aktualisierungstoken (falls vorhanden) abgelaufen sind.

Weitere Informationen

• Einführung in OAuth 2.0