OAuthV2-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation
weitere Informationen

Was

OAuthV2 ist eine mehrzeilige Richtlinie für die Durchführung von OAuth 2.0-Berechtigungstypen. Dies ist die primäre Richtlinie, die zum Konfigurieren von OAuth 2.0-Endpunkten in Apigee Edge verwendet wird.

Tipp: Weitere Informationen zu OAuth in Apigee Edge finden Sie auf der OAuth-Startseite. Sie enthält Links zu Ressourcen, Beispielen, Videos und mehr. Das erweiterte OAuth-Beispiel auf GitHub zeigt ein gutes Beispiel dafür, wie diese Richtlinie in einer funktionierenden Anwendung verwendet wird.

Beispiele

VerifyAccessToken

VerifyAccessToken

Diese OAuthV2-Richtlinienkonfiguration (mit dem Vorgang „VerifyAccessToken“) überprüft, ob ein an Apigee Edge übermitteltes Zugriffstoken gültig ist. Wenn dieser Richtlinienvorgang ausgelöst wird, sucht Edge 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 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

Hinweis: Nur OAuth 2.0-Inhabertokens werden unterstützt. MAC-Tokens (Message Authentication Code) werden nicht unterstützt.

Beispiel:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Standardmäßig akzeptiert Edge Zugriffstokens im Header Authorization mit dem Präfix Bearer. Sie können diese Standardeinstellung mit dem Element <AccessToken> ändern.

GenerateAccessToken

Zugriffstokens generieren

Beispiele dafür, wie Sie Zugriffstokens für die unterstützten Berechtigungstypen anfordern, finden Sie unter Zugriffstoken und Autorisierungscodes anfordern. Das Thema enthält Beispiele für diese Vorgänge:

GenerateAuthorizationCode

Autorisierungscode generieren

Beispiele zum Anfordern von Autorisierungscodes finden Sie unter Autorisierungscode anfordern.

RefreshAccessToken

Zugriffstoken aktualisieren

Beispiele für die Anforderung von Zugriffstokens mit einem Aktualisierungstoken finden Sie unter Zugriffstoken aktualisieren.

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 Variablen "local_clientid" und "local_secret" müssen zuvor festgelegt und verfügbar sein:

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

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

Elementverweis

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

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 Präsenz
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird.

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 Eingestellte Funktionen

<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.

Präsenz Optional
Typ String

<AccessToken>-Element

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

Standardmäßig erwartet VerifyAccessToken, dass das Zugriffstoken im Header Authorization gesendet wird. Sie können diesen Standardwert mit diesem Element ändern. Beispiel: request.queryparam.access_token gibt an, dass das Zugriffstoken als Abfrageparameter mit dem Namen access_token vorhanden sein soll.

Beispiel, in dem <AccessToken>request.header.access_token</AccessToken> angegeben ist:

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
Beispiel für die Angabe von <AccessToken>request.queryparam.access_token</AccessToken>:

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

Standardwert:

Präsenz:

Optional

Typ: String
Wird bei Vorgängen verwendet:
  • VerifyAccessToken

<AccessTokenPrefix> -Element

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Standardmäßig erwartet VerifyAccessToken, dass das Zugriffstoken in einem Autorisierungsheader als Inhabertoken gesendet wird. Beispiel:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Derzeit ist Bearer das einzige unterstützte Präfix.

Standardwert:

Bearer

Präsenz:

Optional

Typ: String
Zulässige Werte:

Bearer

Wird bei Vorgängen verwendet:
  • VerifyAccessToken

<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 Edge 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=ntesla@theramin.com. 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.

Standard:

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.

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 sich Edge nicht daran erinnert, dass das Attribut display ursprünglich in der Richtlinie zum Generieren von Zugriffstoken auf false gesetzt wurde. 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 JavaScript-Richtlinie für die Nachverarbeitung, um alle benutzerdefinierten Attribute, die nicht in der Antwort enthalten sein sollen, manuell zu extrahieren.

Siehe Token und Autorisierungscodes anpassen.

Standardwert:

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.

<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 können Sie angeben, wo Edge nach der Client-ID suchen soll. Der einzige gültige Speicherort, den Sie festlegen können, ist der Standardspeicherort, die Ablaufvariable request.formparam.client_id. Die Festlegung von ClientId auf eine andere Variable wird nicht unterstützt. Siehe auch Zugriffstoken und Autorisierungscodes anfordern.

Standardwert:

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>

Beim Vorgang für den Typ der Autorisierung muss der Client einen Autorisierungscode an den Autorisierungsserver (Apigee Edge) senden. Mit diesem Element können Sie angeben, wo Edge 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. Siehe auch Zugriffstoken und Autorisierungscodes anfordern.

Standardwert:

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 für Aktualisierungstokens <RefreshTokenExpiresIn>.) Der Wert für die Ablaufzeit ist ein vom System generierter Wert plus dem Wert <ExpiresIn>. Wenn <ExpiresIn> auf -1 gesetzt ist, läuft das Token oder der Code gemäß der maximalen Ablaufzeit von OAuth-Zugriffstokens ab. 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.

Mit Apigee Edge for Public Cloud behält Edge die folgenden Entitäten mindestens 180 Sekunden lang im Cache, nachdem auf die Entitäten zugegriffen wurde.

  • OAuth Zugriffstoken Dies bedeutet, dass ein widerrufenes Token möglicherweise weiterhin bis zu drei Minuten gültig ist, bis sein Cache-Limit abgelaufen ist.
  • 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>

Edge unterstützt keine Möglichkeit, den Ablauf 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 dem Ablauf automatisch aus dem Apigee Edge-System gelöscht. Weitere Informationen finden Sie unter Zugriffstokens bereinigen.

Private Cloud: Bei einer Edge for Private Cloud-Installation wird der Standardwert durch das Attribut conf_keymanagement_oauth_auth_code_expiry_time_in_millis festgelegt. So legen Sie diese Eigenschaft fest:

  1. Öffnen Sie die Datei message-processor.properties in einem Editor. Wenn die Datei nicht vorhanden ist, erstellen Sie sie:
    vi /opt/apigee/customer/application/message-processor.properties
  2. Legen Sie das Attribut wie gewünscht fest:
    conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
  3. Achten Sie darauf, dass die Attributdatei dem Nutzer „apigee“ gehört:
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. Starten Sie den Message Processor neu.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Standardwert:

Wenn keine Angabe erfolgt, wendet das System einen auf Systemebene konfigurierten Standardwert an.

Präsenz:

Optional

Typ: Ganzzahl
Zulässige Werte:
  • Beliebige positive Ganzzahl ungleich null. 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.
  • -1 läuft gemäß dem maximalen OAuth-Zugriffstoken ab.

    HINWEIS: Die Angabe einer anderen negativen Ganzzahl oder null verursacht einen Bereitstellungsfehler.

    Siehe auch Antipattern: Lange Ablaufzeit für OAuth-Tokens festlegen.

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 Edge mit, wo ein externes Zugriffstoken zu finden ist (ein Zugriffstoken, das nicht von Apigee Edge generiert wurde).

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 Edge die client_id und den client_secret normal mit dem Apigee Edge-Autorisierungsspeicher. 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.

Standard:

false

Präsenz:

Optional

Typ: Boolesch
Zulässige Werte: Richtig oder falsch?
Wird mit Berechtigungstypen verwendet:
  • authorization_code
  • Passwort
  • client_credentials

{ExternalAuthorizationCode} -Element

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

Teilt Apigee Edge mit, wo ein externer Authentifizierungscode zu finden ist (ein Authentifizierungscode, der nicht von Apigee Edge generiert wurde).

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 Edge mit, wo ein externes Aktualisierungstoken zu finden ist (ein Aktualisierungstoken, das nicht von Apigee Edge 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 dieser Wert auf true gesetzt ist, wird von der Richtlinie eine Antwort generiert und zurückgegeben. 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" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Bei false wird keine Antwort gesendet. Stattdessen enthält eine Reihe von Ablaufvariable 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.

Standardwert:

false

Präsenz:

Optional

Typ: String
Zulässige Werte: Richtig oder falsch?
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.

Standardwert:

false

Präsenz:

Optional

Typ: String
Zulässige Werte: Richtig oder falsch?
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 Zugriffstoken und Autorisierungscodes anfordern.

Standard:

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.

Standardwert:

Wenn <Operation> nicht angegeben ist, prüft Edge 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:

<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. Mit den Elementen <PassWord> und <UserName> werden Variablen angegeben, wo Edge 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 mithilfe eines Abfrageparameters übergeben und das Element so festlegen: <PassWord>request.queryparam.password</PassWord>. Wenn das Passwort in einem HTTP-Header erforderlich sein soll, legen Sie diesen Wert auf request.header.password fest.

Die OAuthV2-Richtlinie führt nichts weiter mit diesen Anmeldedatenwerten aus. Edge ü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 Zugriffstokens und Autorisierungscodes anfordern.

Standard:

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

<RedirectUri> -Element

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

Gibt an, wo Edge 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 (Edge) mit, wohin ein Autorisierungscode (für den Authentifizierungscode-Berechtigungstyp) 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 Entwickler-Apps in Edge und zum Angeben einer Callback-URL finden Sie unter Apps registrieren und API-Schlüssel verwalten.

  • (Optional) Wenn eine Callback-URL registriert ist und redirect_uri in der Anfrage fehlt, leitet Edge zur registrierten Callback-URL weiter.
  • (erforderlich) Wenn eine Callback-URL nicht registriert ist, ist redirect_uri erforderlich. Beachten Sie, dass Edge in diesem Fall JEDE 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 Zugriffstoken und Autorisierungscodes anfordern.

Standardwert:

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 Edge 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 Zugriffstoken und Autorisierungscodes anfordern.

Standard:

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> auf -1 eingestellt ist, läuft das Aktualisierungstoken gemäß dem maximalen OAuth-Aktualisierungstoken-Ablauf ab. Wenn <RefreshTokenExpiresIn> nicht angegeben ist, ist die Ablaufzeit standardmäßig unbegrenzt.

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">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Private Cloud: Bei einer Edge for Private Cloud-Installation wird der Standardwert durch das Attribut conf_keymanagement_oauth_refresh_token_expiry_time_in_millis festgelegt. So legen Sie diese Eigenschaft fest:

  1. Öffnen Sie die Datei message-processor.properties in einem Editor. Wenn die Datei nicht vorhanden ist, erstellen Sie sie:
    vi /opt/apigee/customer/application/message-processor.properties
  2. Legen Sie das Attribut wie gewünscht fest:
    conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
  3. Achten Sie darauf, dass die Attributdatei dem Nutzer „apigee“ gehört:
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. Starten Sie den Message Processor neu.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Standardwert:

Wenn keine Angabe erfolgt, wendet das System einen auf Systemebene konfigurierten Standardwert an.

Präsenz:

Optional

Typ: Ganzzahl
Zulässige Werte:
Wird mit Berechtigungstypen verwendet:
  • authorization_code
  • Passwort
  • refresh_token

<ResponseType>-Element

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

Dieses Element informiert Edge, welchen Berechtigungstyp die Client-App anfordert. Sie wird nur mit dem Autorisierungscode und den impliziten Berechtigungstypen verwendet.

Standardmäßig sucht Edge in einem response_type-Abfrageparameter nach dem Wert des Antworttyps. 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 Edge nach dem Antworttyp, der im Anfrageheader übergeben wird. Siehe auch Zugriffstoken und Autorisierungscodes anfordern.

Standard:

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 ein neues Aktualisierungstoken von Apigee Edge ausgegeben, wenn ein gültiges Aktualisierungstoken angezeigt wird.

Standardwert:

false

Präsenz:

optional

Typ: boolean
Zulässige Werte:

true oder false

Wird mit Berechtigungstyp verwendet:
  • refresh_token

<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 Zugriffstokens und Autorisierungscodes anfordern.

Standard:

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>

In Fällen, in denen die Client-App die Statusinformationen an den Autorisierungsserver senden muss, können Sie mit diesem Element angeben, wo Edge 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. Weitere Informationen finden Sie unter Zugriffstokens und Autorisierungscodes anfordern.

Standard:

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 Edge an, das externe Zugriffstoken zu speichern. Andernfalls wird es nicht beibehalten.

Standard:

false

Präsenz:

Optional

Typ: Boolesch
Zulässige Werte: Richtig oder falsch?
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 Berechtigungstypen an, die von einem OAuth-Token-Endpunkt in Apigee Edge unterstützt werden. 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. Sehen Sie sich auch das Element <GrantType> an. Dabei handelt es sich um ein übergeordnetes Element, mit dem angegeben wird, wo Apigee Edge nach dem grant_type-Parameter suchen soll, der in einer Clientanfrage übergeben wird. Edge sorgt dafür, dass der Wert des Parameters grant_type mit einem der unterstützten Berechtigungstypen übereinstimmt.

Standardwert:

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. Mit den Elementen <PassWord> und <UserName> werden Variablen angegeben, wo Edge 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 haben beispielsweise die Möglichkeit, den Nutzernamen in einem Abfrageparameter zu übergeben und das Element <UserName> so festzulegen: <UserName>request.queryparam.username</UserName>.Wenn der Nutzername in einem HTTP-Header erforderlich sein soll, legen Sie diesen Wert auf request.header.username fest.

Die OAuthV2-Richtlinie führt nichts weiter mit diesen Anmeldedatenwerten aus. Edge ü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 Zugriffstokens und Autorisierungscodes anfordern.

Standardwert:

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 Zugriffstokens und Autorisierungscodes anfordern.

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 von Flussvariablen in den Ausführungskontext des Proxys eingefügt. Diese Variablen geben Ihnen Attribute zu, die sich auf das Zugriffstoken, die Entwickleranwendung, den Entwickler und das Unternehmen 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.

Tokenspezifische Variablen

Variablen Beschreibung
organization_name Der Name der Organisation, in der der Proxy ausgeführt wird.
developer.id Die ID des Entwicklers, der der registrierten Clientanwendung zugeordnet ist.
developer.app.name Der Name des Entwicklers, der mit der registrierten Clientanwendung verknüpft ist.
client_id Die Client-ID der registrierten Clientanwendung.
grant_type Die Art des Berechtigungstyps, die der Anfrage zugeordnet ist.
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.

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.

Entwicklerspezifische Variablen

Wenn für "app.appType" der Wert "Company" (Unternehmen) festgelegt ist, werden die Unternehmensattribute ausgefüllt und "app.appType" auf "Developer" gesetzt.

Variablen Beschreibung
Entwicklerspezifische Variablen
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status "Aktiv" oder "Inaktiv"
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} Ein benanntes benutzerdefiniertes Attribut des Entwicklers.

Unternehmensspezifische Variablen

Wenn für "app.appType" der Wert "Company" (Unternehmen) festgelegt ist, werden die Unternehmensattribute ausgefüllt und "app.appType" auf "Developer" gesetzt.

Variablen Beschreibung
company.id
company.displayName
company.apps
company.appOwnerStatus
company.created_by
company.created_at
company.last_modified_at
company.last_modified_by
company.{custom_attributes} Ein benanntes benutzerdefiniertes Attribut des Unternehmens.

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

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese 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 Wird nach Vorgängen ausgelöst
steps.oauth.v2.access_token_expired 401 Das Zugriffstoken ist abgelaufen.

VerifyAccessToken
InvalidateToken

steps.oauth.v2.access_token_not_approved 401 Das Zugriffstoken wurde widerrufen. VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 Die angeforderte Ressource existiert nicht für die mit dem Zugriffstoken verknüpften API-Produkte. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 Die Richtlinie, die in einer im Element <AccessToken> angegebenen Variablen nach einem Zugriffstoken suchen, konnte aber die Variable nicht auflösen. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 Die Richtlinie erwartete einen Autorisierungscode in einer Variablen, die im Element <Code> angegeben ist, die Variable konnte jedoch nicht aufgelöst werden. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 Die Richtlinie, die die Client-ID in einer im Element <ClientId> angegebenen Variable finden muss, konnte aber nicht aufgelöst werden. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplictGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 Die Richtlinie, von der ein Aktualisierungstoken in einer im <RefreshToken>-Element angegebenen Variablen gefunden wird, konnte aber nicht aufgelöst werden. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 Die Richtlinie, von der ein Token in einer im <Tokens>-Element angegebenen Variable erwartet wird, konnte aber nicht aufgelöst werden.

ValidateToken
InvalidateToken

steps.oauth.v2.InsufficientScope 403 Der in der Anfrage enthaltene Zugriffstoken hat einen Bereich, der nicht mit dem in der Richtlinie des Zugriffs-Token angegebenen Bereichs übereinstimmt. Weitere Informationen zum Umfang finden Sie unter Mit OAuth2-Bereichen arbeiten. VerifyAccessToken
steps.oauth.v2.invalid_access_token 401 Das vom Client gesendete Zugriffstoken ist ungültig. VerifyAccessToken
steps.oauth.v2.invalid_client 401

Dieser Fehlername wird zurückgegeben, wenn das Attribut <GenerateResponse> der Richtlinie auf true und die in der Anfrage gesendete Client-ID ungültig ist. Achten Sie darauf, dass Sie die richtigen Clientschlüssel und Secret-Werte für die mit Ihrem Proxy verknüpfte Entwickler-App verwenden. In der Regel werden diese Werte als Base64-codierter Basic Authorization-Header gesendet.

Hinweis:Es wird empfohlen, die bestehenden Bedingungen für Fehlerregeln zu ändern, damit die Namen invalid_client und InvalidClientIdentifier erfasst werden. Weitere Informationen und ein Beispiel finden Sie in den Versionshinweisen zu 16.09.21.

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.invalid_request 400 Dieser Fehlername wird für verschiedene Arten von Fehlern verwendet, in der Regel für fehlende oder falsche Parameter, die in der Anfrage gesendet werden. Wenn <GenerateResponse> auf false gesetzt ist, verwenden Sie Fehlervariablen (siehe unten), um Details zum Fehler wie den Fehlernamen und die Ursache abzurufen. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplictGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 Der Autorisierungs-Header enthält nicht das Wort "Bearer". Beispiel: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNo\
steps.oauth.v2.ApiProductMatchFound
401

Der API-Proxy befindet sich nicht in dem Produkt, das mit dem Zugriffstoken verknüpft ist.

Tipps: Das mit dem Zugriffstoken verknüpfte Produkt muss ordnungsgemäß konfiguriert sein. Wenn Sie in Ressourcenpfaden Platzhalter verwenden, achten Sie darauf, dass die Platzhalter richtig verwendet werden. Weitere Informationen finden Sie unter API-Produkte erstellen.

Weitere Informationen zu den Ursachen dieses Fehlers finden Sie in diesem Apigee-Community-Beitrag.

VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

Dieser Fehlername wird zurückgegeben, wenn das Attribut <GenerateResponse> der Richtlinie auf false und die in der Anfrage gesendete Client-ID ungültig ist. Achten Sie darauf, dass Sie die richtigen Clientschlüssel und Secret-Werte für die mit Ihrem Proxy verknüpfte Entwickleranwendung verwenden. Normalerweise werden diese Werte als Base64-codierter Basisautorisierungs-Header gesendet.

Hinweis: In diesem Fall hieß dieser Fehler invalid_client. Es wird empfohlen, die bestehenden Bedingungen für Fehlerregeln zu ändern, damit die Namen invalid_client und InvalidClientIdentifier erfasst werden. Weitere Informationen und ein Beispiel finden Sie in den Versionshinweisen zu 16.09.21.

GenerateAccessToken
RefreshAccessToken

steps.oauth.v2.InvalidParameter 500 Die Richtlinie muss entweder ein Zugriffstoken oder einen Autorisierungscode angeben, jedoch nicht beides. GenerateAuthorizationCode
GenerateAccessTokenImplictGrant
steps.oauth.v2.InvalidTokenType 500 Für das Element <Tokens>/<Token> müssen Sie den Tokentyp angeben, z. B. refreshtoken. Wenn der Client den falschen Typ übergibt, wird dieser Fehler ausgegeben. ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 Der Antworttyp lautet token, es sind jedoch keine Angabetypen angegeben. GenerateAuthorizationCode
GenerateAccessTokenImplictGrant
steps.oauth.v2.UnSupportedGrantType 500

Der Client hat eine Art der Gewährung angegeben, die von der Richtlinie nicht unterstützt wird (nicht im Element <SupportedGrantTypes> aufgeführt).

Hinweis: Derzeit gibt es einen Programmfehler, durch den nicht unterstützte Gewährfehler nicht ordnungsgemäß ausgelöst werden. Wenn ein nicht unterstützter Berechtigungstyp auftritt, meldet der Proxy den Fehlerfluss nicht wie erwartet.

GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplictGrant
RefreshAccessToken

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Ursache
InvalidValueForExpiresIn

Für das <ExpiresIn>-Element sind gültige Werte positive Ganzzahlen und -1.

InvalidValueForRefreshTokenExpiresIn Für das <RefreshTokenExpiresIn>-Element sind gültige Werte positive Ganzzahlen und -1.
InvalidGrantType Im Element <SupportedGrantTypes> ist ein ungültiger Zugriffstyp angegeben. Eine Liste der gültigen Typen finden Sie in der Richtlinienreferenz.
ExpiresInNotApplicableForOperation Die im <Operations>-Element angegebenen Vorgänge müssen ablaufen. Der Vorgang "VerifyToken" beispielsweise nicht.
RefreshTokenExpiresInNotApplicableForOperation Achten Sie darauf, dass die im <Operations>-Element angegebenen Vorgänge das Ablaufdatum des Aktualisierungstokens unterstützen. Der Vorgang "VerifyToken" beispielsweise nicht.
GrantTypesNotApplicableForOperation Achten Sie darauf, dass die in <SupportedGrantTypes> angegebenen Förderungstypen für den angegebenen Vorgang unterstützt werden.
OperationRequired

Sie müssen in dieser Richtlinie einen Vorgang mithilfe des <Operation>-Elements angeben.

Hinweis: Wenn das Element <Operation> fehlt, gibt die Benutzeroberfläche einen Schemavalidierungsfehler aus.

InvalidOperation

Mit dem Element <Operation> müssen Sie in dieser Richtlinie einen gültigen Vorgang angeben.

Hinweis: Wenn das Element <Operation> ungültig ist, gibt die Benutzeroberfläche einen Schemavalidierungsfehler aus.

TokenValueRequired Sie müssen einen <Token>-Tokenwert im Element <Tokens> angeben.

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 = "invalid_request"
oauthV2.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. oauthV2.GenerateAccesstoken.fault.name = invalid_request

Hinweis: Für den VerifyAccessToken-Vorgang enthält der Fehlername dieses Suffix: keymanagement.service
Beispiel: keymanagement.service.invalid_access_token

oauthV2.policy_name.fault.cause policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Beispiel für eine Fehlerantwort

Diese Antworten werden an den Client zurückgesendet, wenn das Element <GenerateResponse> den Wert true hat.

Wenn <GenerateResponse> true ist, gibt die Richtlinie Fehler in diesem Format für Vorgänge zurück, die Tokens und Codes generieren. Eine vollständige Liste finden Sie in der Referenz zur OAuth-HTTP-Fehlerantwort.

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

Wenn <GenerateResponse> true ist, gibt die Richtlinie Fehler in diesem Format zur Überprüfung und Überprüfung zurück. Eine vollständige Liste finden Sie in der Referenz zur OAuth-HTTP-Fehlerantwort.

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

Beispiel für eine Fehlerregel

<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>

Richtlinienschema

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

Mit der standardmäßigen OAuth-Konfiguration arbeiten

Jede Organisation (auch eine kostenlose Testorganisation) auf Apigee Edge 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 Edge erstellen. Weitere Informationen finden Sie unter Informationen zu OAuth-Endpunkten.

Zugriffstokens löschen

Standardmäßig werden OAuth2-Tokens 3 Tage (259.200 Sekunden) nach Ablauf des Zugriffstokens und des Aktualisierungstokens (falls vorhanden) aus dem Apigee Edge-System gelöscht. In einigen Fällen kann es sinnvoll sein, diese Standardeinstellung zu ändern. Beispielsweise können Sie die Löschzeit verkürzen, um Speicherplatz zu sparen, wenn eine große Anzahl von Tokens generiert wird.

Wenn Sie Edge for Private Cloud verwenden, können Sie diese Standardeinstellung ändern. Dazu legen Sie die Organisationsattribute fest, wie in diesem Abschnitt beschrieben. (Das dreitägige dauerhafte Löschen abgelaufener Token gilt für Edge für Private Cloud Version 4.19.01 und höher. Bei früheren Versionen beträgt das standardmäßige Löschintervall 180 Tage.

Löschen der Einstellungen für Edge Private Cloud 4.16.01 und höher aktualisieren

Hinweis:Nur Tokens, die nach der Anwendung dieser Einstellungen generiert wurden, sind davon betroffen. Die Einstellungen gelten nicht für Tokens, die zuvor generiert wurden.

Dauerhafte Einstellungen für Edge Private Cloud 4.15.07 aktualisieren

Hinweis:Nur Tokens, die nach der Anwendung dieser Einstellungen generiert wurden, sind davon betroffen. Die Einstellungen gelten nicht für Tokens, die zuvor generiert wurden.

Nicht RFC-konformes Verhalten

Die OAuthV2-Richtlinie gibt eine Tokenantwort zurück, die bestimmte nicht RFC-kompatible Eigenschaften enthält. Die folgende Tabelle zeigt die nicht konformen Attribute, die von der OAuthV2-Richtlinie und den entsprechenden konformen Attributen zurückgegeben wurden.

an.
OAuthV2 gibt Folgendes zurück: Die RFC-kompatible Eigenschaft lautet:
"token_type":"BearerToken" "token_type":"Bearer"
"expires_in":"3600" "expires_in":3600

(Der konforme Wert ist eine Zahl, kein String.)

Die Fehlerantwort für ein abgelaufenes Aktualisierungstoken, wenn grant_type = refresh_token:

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

Die RFC-konforme Antwort lautet jedoch:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Weitere Informationen