OAuthV2-Richtlinie

Sie sehen sich die Dokumentation zu Apigee Edge an.
Rufen Sie die Dokumentation zu Apigee X auf. Weitere Informationen

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

Tipp:Weitere Informationen zu OAuth in Apigee Edge finden Sie auf der OAuth-Startseite. Sie enthält Links zu Ressourcen, Beispielen, Videos und mehr. Im erweiterten OAuth-Beispiel auf GitHub wird gezeigt, wie diese Richtlinie in einer funktionierenden Anwendung verwendet wird.

Beispiele

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

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

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

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

Siehe auch 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:

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

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

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

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

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

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

<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. Das liegt daran, dass Edge 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.

<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 nach der Client-ID in der Ablaufvariablen request.formparam.client_id suchen soll. Die Festlegung von ClientId auf eine andere Variable wird nicht unterstützt. Siehe auch Zugriffstoken und Autorisierungscodes anfordern.

<Code>-Element

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

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

<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> auf -1 gesetzt ist, läuft das Token oder der Code gemäß der maximalen Ablaufzeit des 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.

Bei Apigee Edge for Public Cloud speichert Edge die folgenden Entitäten für mindestens 180 Sekunden im Cache, nachdem auf die Entitäten zugegriffen wurde.

• OAuth Zugriffstoken Daher kann ein widerrufenes Token noch bis zu drei Minuten lang erfolgreich sein, bis sein Cache-Limit abläuft.
• 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, 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 Edge-System entfernt. Weitere Informationen finden Sie unter Zugriffstokens bereinigen.

Private Cloud: Bei einer Edge für Private Cloud-Installation wird der Standardwert durch das Attribut conf_keymanagement_oauth_auth_code_expiry_time_in_millis festgelegt. So legen Sie diese Property 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 die Property wie gewünscht fest:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Der Inhaber der Properties-Datei muss der Nutzer „apigee“ sein:

   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

<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 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 Edge die client_id und den client_secret normalerweise anhand des Apigee Edge-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.

{ExternalAuthorizationCode} -Element

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

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

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.

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

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

<Operation>-Element

<Operation>GenerateAuthorizationCode</Operation>

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

<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, in denen 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 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. 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.

<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, 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 Edge und zum Festlegen einer Callback-URL finden Sie unter Anwendungen registrieren und API-Schlüssel verwalten.

• (optional) Wenn eine Callback-URL registriert ist und redirect_uri in der Anfrage fehlt, leitet Edge an die registrierte 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.

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

<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, wendet das System einen auf Systemebene konfigurierten Standardwert an. Weitere Informationen zu den Standardeinstellungen des Systems erhalten Sie vom Apigee Edge-Support.

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 für Private Cloud-Installation wird der Standardwert durch das Attribut conf_keymanagement_oauth_refresh_token_expiry_time_in_millis festgelegt. So legen Sie diese Property 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 die Property wie gewünscht fest:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Der Inhaber der Properties-Datei muss der Nutzer „apigee“ sein:

   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

<ResponseType>-Element

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

Dieses Element informiert Edge darüber, 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 Anfrage-Header übergeben wird. Siehe auch Zugriffstoken und Autorisierungscodes anfordern.

<ReuseRefreshToken> -Element

<ReuseRefreshToken>true</ReuseRefreshToken>

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

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

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

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

<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 Edge 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 Edge nach dem Parameter grant_type sucht, der in einem Client übergeben wird Anfrage festgelegt werden. Edge sorgt dafür, dass der Wert des Parameters grant_type mit einem der unterstützten Berechtigungstypen übereinstimmt.

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

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.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

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"

Der Vorgang „VerifyAccessToken“ wird ausgeführt. Eine große Anzahl von Ablaufvariablen wird im Ausführungskontext des Proxys dargestellt. 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

Anwendungsspezifische Variablen

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

Entwicklerspezifische Variablen

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

Unternehmensspezifische Variablen

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

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

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

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

Fehlerreferenz

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

Fault variables

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

Example error response

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

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>

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 Organisation in 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 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 Edge-System gelöscht, nachdem das Zugriffstoken und das Aktualisierungstoken (falls vorhanden) abgelaufen sind. 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, indem Sie Organisationseigenschaften festlegen, wie in diesem Abschnitt erläutert. (Die automatische Löschung abgelaufener Tokens nach drei Tagen gilt für Edge for Private Cloud Version 4.19.01 und höher. Bei früheren Versionen beträgt das standardmäßige Löschintervall 180 Tage.

Aktualisieren der Löscheinstellungen für Edge Private Cloud 4.16.01 und höher

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

Aktualisierung der Löscheinstellungen für Edge Private Cloud 4.15.07

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

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.

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

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

Die RFC-konforme Antwort lautet jedoch:

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

Weitere Informationen

• Einführung in OAuth 2.0