VerifyAPIKey-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Übersicht

Mit der Richtlinie zum Prüfen des API-Schlüssels können Sie die Verifizierung von API-Schlüsseln zur Laufzeit erzwingen, sodass nur Anwendungen mit genehmigten API-Schlüsseln auf Ihre APIs zugreifen können. Mit dieser Richtlinie wird sichergestellt, dass API-Schlüssel gültig sind, nicht widerrufen wurden und für die Nutzung der spezifischen Ressourcen freigegeben wurden, die mit Ihren API-Produkten verknüpft sind.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Eine Anleitung zum Erstellen eines API-Proxys, der die API-Schlüsselrichtlinie prüft, finden Sie unter API durch Anfordern von API-Schlüsseln sichern.

Beispiele

Schlüssel im Abfrageparameter

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

In diesem Beispiel erwartet die Richtlinie den API-Schlüssel in einer Ablaufvariablen namens request.queryparam.apikey. Die Variable request.queryparam.{name} ist eine Standard-Apigee-Ablaufvariable, die mit dem Wert eines Abfrageparameters gefüllt wird, der in der Clientanfrage übergeben wird.

Der folgende curl-Befehl übergibt den API-Schlüssel in einem Abfrageparameter:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

Schlüssel im Header

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

In diesem Beispiel erwartet die Richtlinie den API-Schlüssel in einer Ablaufvariablen namens request.header.x-apikey. Die Variable request.header.{name} ist eine Standard-Apigee-Flussvariable, die den Wert eines Headers enthält, der in der Clientanfrage übergeben wird.

Im folgenden cURL wird gezeigt, wie der API-Schlüssel in einem Header übergeben wird:

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

Schlüssel in der Variablen

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

Die Richtlinie kann auf jede Variable verweisen, die den Schlüssel enthält. Die Richtlinie in diesem Beispiel extrahiert den API-Schlüssel aus einer Variablen mit dem Namen requestAPIKey.key.

Wie diese Variable ausgefüllt wird, liegt ganz bei Ihnen. Sie können beispielsweise die Richtlinie "Variablen extrahieren" verwenden, um requestAPIKey.key aus einem Abfrageparameter namens myKey auszufüllen, wie unten gezeigt:

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Ablaufvariablen für Zugriffsrichtlinien

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Apigee füllt automatisch eine Reihe von Flussvariablen aus, wenn sie die Richtlinie zum Prüfen des API-Schlüssels für einen gültigen API-Schlüssel ausführen. Sie können diese Variablen verwenden, um auf Informationen wie den Namen der App, die App-ID und Informationen zum Entwickler oder Unternehmen zuzugreifen, der die App registriert hat. Im obigen Beispiel verwenden Sie die Richtlinie "Nachricht zuweisen", um auf den Vornamen, den Nachnamen und die E-Mail-Adresse des Entwicklers zuzugreifen, nachdem der API-Schlüssel verifiziert wurde.

Diese Variablen haben das Präfix:

verifyapikey.{policy_name}

In diesem Beispiel lautet der Name der API-Schlüsselrichtlinie "Verify-api-key". Daher verweisen Sie auf den Vornamen des Entwicklers, der die Anfrage stellt, indem Sie auf die Variable verifyapikey.verify-api-key.developer.firstName. zugreifen.

Apigee verstehen

Informationen zur Richtlinie "API-Schlüssel prüfen"

Wenn ein Entwickler eine Anwendung bei Apigee registriert, generiert Apigee automatisch einen Consumer-Schlüssel und ein Secret-Paar. Sie können den Consumer-Key und das Secret-Paar der Anwendung in der Apigee-Benutzeroberfläche sehen oder über die Apigee API darauf zugreifen.

Zum Zeitpunkt der App-Registrierung wählt der Entwickler ein oder mehrere API-Produkte aus, die mit der App verknüpft werden sollen. Ein API-Produkt ist eine Sammlung von Ressourcen, auf die über API-Proxys zugegriffen werden kann. Der Entwickler übergibt dann den API-Schlüssel (Consumer-Key) als Teil jeder Anfrage an eine API in einem der Anwendung zugeordneten API-Produkt. Weitere Informationen finden Sie unter Veröffentlichungsübersicht.

API-Schlüssel können als Authentifizierungstoken verwendet werden. Sie können aber auch zum Abrufen von OAuth-Zugriffstokens verwendet werden. In OAuth werden API-Schlüssel als "Client-ID" bezeichnet. Die Namen können austauschbar verwendet werden. Weitere Informationen finden Sie unter OAuth-Startseite.

Apigee füllt beim Ausführen der Verify API Key-Richtlinie automatisch eine Reihe von Flussvariablen aus. Weitere Informationen zu Flow-Variablen finden Sie weiter unten.

Elementreferenz

Die folgenden Elemente und Attribute können Sie für diese Richtlinie konfigurieren:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

<VerifyAPIKey>-Attribute

Das folgende Beispiel zeigt die Attribute für das Tag <VerifyAPIKey>:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

 N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails. See also:

 false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

 true Optional
async

This attribute is deprecated.

 false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.
Presence Optional
Type String

<APIKey>-Element

Mit diesem Element wird die Flussvariable angegeben, die den API-Schlüssel enthält. In der Regel sendet der Client den API-Schlüssel in einem Abfrageparameter, einem HTTP-Header oder einem Formularparameter. Wenn der Schlüssel beispielsweise in einem Header namens x-apikey gesendet wird, ist der Schlüssel in der Variable request.header.x-apikey zu finden.

Standard –
Präsenz Erforderlich
Typ String

Attribute

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

Attribut Beschreibung Standard Präsenz
ref

Ein Verweis auf die Variable, die den API-Schlüssel enthält. Pro Richtlinie ist nur ein Standort zulässig.

 – Erforderlich

Beispiele

In diesen Beispielen werden der Schlüssel und Parameter wie ein Header mit dem Namen x-apikey übergeben.

Als Abfrageparameter:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

Als HTTP-Header:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

Als HTTP-Formularparameter:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

<CacheExpiryInSeconds> Element

Dieses Element erzwingt eine TTL für den Cache, die die Anpassung des Zeitraums für den Ablauf des Zugriffstokens ermöglicht. Der unterstützte Bereich liegt zwischen 1 und 180 Sekunden. Sie können eine Ablaufvariable und eine Standardvariable angeben. Wenn angegeben, hat der Ablaufvariablenwert Vorrang vor dem angegebenen Standardwert. 

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
Standard –

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

Attribute

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

Attribut Beschreibung Standard Präsenz
ref

Ein Verweis auf die Ablaufvariable mit dem Wert für den Cache-Ablauf, ausgedrückt in Sekunden.

Wenn angegeben, hat der Ablaufvariablenwert Vorrang vor dem angegebenen Standardwert.

 – Optional

Schemas

Ablaufvariablen

Wenn eine Richtlinie zur Bestätigung des API-Schlüssels für einen gültigen API-Schlüssel erzwungen wird, füllt Apigee eine Reihe von Ablaufvariablen. Diese Variablen sind für Richtlinien oder Code verfügbar, die später im Ablauf ausgeführt werden. Sie werden häufig verwendet, um auf Grundlage des Attributs des API-Schlüssels wie dem Anwendungsnamen oder dem API-Produkt, das zur Autorisierung des Schlüssels verwendet wird, um eine benutzerdefinierte Verarbeitung oder benutzerdefinierte Attribute des API-Schlüssels durchzuführen.

Die Richtlinie füllt verschiedene Arten von Ablaufvariablen aus, einschließlich:

  • Allgemein
  • App
  • Entwickler
  • Analyse
  • Monetarisierung

Jeder Typ von Ablaufvariablen hat ein anderes Präfix. Alle Variablen sind Skalare, mit Ausnahme derer, die als Arrays angegeben sind.

Allgemeine Ablaufvariablen

In der folgenden Tabelle sind die allgemeinen Ablaufvariablen aufgeführt, die von der Richtlinie "API-Schlüssel prüfen" ausgefüllt werden. Diese Variablen haben das Präfix:

verifyapikey.{policy_name}

Beispiel: verifyapikey.{policy_name}.client_id

Folgende Variablen sind verfügbar:

Variable Beschreibung
client_id Der Consumer-Key (auch als API-Schlüssel oder App-Schlüssel bezeichnet), der von der anfordernden App bereitgestellt wird.
client_secret Das Consumer-Secret für den Consumer-Key.
redirection_uris Alle Weiterleitungs-URIs in der Anfrage
developer.app.id

Die ID des Entwicklers oder der Anwendung AppGroup, von der die Anfrage stammt.
developer.app.name Der Anwendungsname des Entwicklers oder der Anwendung AppGroup, von der die Anfrage stammt.
developer.id

Die ID des Entwicklers oder der AppGroup, die als Inhaber der anfragenden App registriert ist.
developer.{custom_attrib_name} Alle benutzerdefinierten Attribute, die aus dem App-Schlüsselprofil abgeleitet wurden.
DisplayName Der Wert des Attributs <DisplayName> der Richtlinie.
failed Wird auf "true" gesetzt, wenn die API-Schlüsselvalidierung fehlschlägt.
{custom_app_attrib} Jedes benutzerdefinierte Attribut, das aus dem App-Profil abgeleitet wird. Geben Sie den Namen des benutzerdefinierten Attributs an.
apiproduct.name* Der Name des API-Produkts, das zur Validierung der Anfrage verwendet wird.
apiproduct.{custom_attrib_name}* Jedes benutzerdefinierte Attribut, das vom API-Produktprofil abgeleitet wird.
apiproduct.developer.quota.limit* Das für das API-Produkt festgelegte Kontingentlimit, falls vorhanden.
apiproduct.developer.quota.interval* Das für das API-Produkt festgelegte Kontingentintervall, falls vorhanden.
apiproduct.developer.quota.timeunit* Die Kontingenteinheit, die für das API-Produkt festgelegt wurde, sofern vorhanden.
* API-Produktvariablen werden automatisch ausgefüllt, wenn die API-Produkte mit einer gültigen Umgebung, Proxys und Ressourcen konfiguriert sind (abgeleitet vom proxy.pathsuffix). Eine Anleitung zum Einrichten von API-Produkten finden Sie unter API-Produkte verwalten.

App-Ablaufvariablen

Folgende Ablaufvariablen, die Informationen über die Anwendung enthalten, werden durch die Richtlinie ausgefüllt. Diese Variablen haben das Präfix:

verifyapikey.{policy_name}.app.

Beispiele:

verifyapikey.{policy_name}.app.name

Folgende Variablen sind verfügbar:

Variable Beschreibung
name Der Name der Anwendung
id ID der App
accessType Wird von Apigee nicht verwendet.
callbackUrl Die Callback-URL der App wird normalerweise nur für OAuth verwendet.
DisplayName Der Anzeigename der App
status Der Status der Anwendung, z. B. "Genehmigt" oder "Widerruf".
apiproducts Ein Array, das die Liste der API-Produkte enthält, die der App zugeordnet sind.
appFamily Jede App-Familie, in der die App enthalten ist, oder "Standard".
appParentStatus Der Status der übergeordneten Anwendung, z. B. "Aktiv" oder "Inaktiv"
appType Der Anwendungstyp "Entwickler".
appParentId Die ID der übergeordneten App.
created_at Datum und Uhrzeit, zu der die App erstellt wurde.
created_by Die E-Mail-Adresse des Entwicklers, der die App erstellt hat.
last_modified_at Das Datum und der Zeitstempel der letzten App-Aktualisierung.
last_modified_by Die E-Mail-Adresse des Entwicklers, der die App zuletzt aktualisiert hat.
{app_custom_attributes} Jedes benutzerdefinierte App-Attribut. Geben Sie den Namen des benutzerdefinierten Attributs an.

AppGroup-Ablaufvariablen

Die folgenden Ablaufvariablen mit Informationen zu den AppGroups werden von der Richtlinie ausgefüllt. Diese AppGroup-Attribute werden nur ausgefüllt, wenn verifyapikey.{policy_name}.app.appType "AppGroup" ist.

Diese Variablen haben das Präfix:

verifyapikey.{policy_name}.appgroup.

Beispiele:

verifyapikey.{policy_name}.appgroup.name

Folgende Variablen sind verfügbar:

Variable Beschreibung
name Der Name der AppGroup.
id Die AppGroup-ID.
displayName Der Anzeigename der AppGroup.
appOwnerStatus Der Status des App-Inhabers: „active“, „inactive“ oder „login_lock“.
created_at Das Datum/die Uhrzeit, zu der die AppGroup erstellt wurde.
created_by Die E-Mail-Adresse des Entwicklers, der die AppGroup erstellt hat.
last_modified_at Der Datums-/Zeitstempel, zu dem die AppGroup zuletzt geändert wurde.
last_modified_by Die E-Mail-Adresse des Entwicklers, der die AppGroup zuletzt geändert hat.
{appgroup_custom_attributes} Jedes benutzerdefinierte AppGroup-Attribut. Geben Sie den Namen des benutzerdefinierten Attributs an.

Entwickler-Ablaufvariablen

Die folgenden Ablaufvariablen mit Informationen über den Entwickler werden von der Richtlinie ausgefüllt. Diese Variablen haben das Präfix:

verifyapikey.{policy_name}.developer

Beispiele:

verifyapikey.{policy_name}.developer.id

Folgende Variablen sind verfügbar:

Variable Beschreibung
id Gibt {org_name}@@@{developer_id} zurück
userName Nutzername des Entwicklers
firstName Vorname des Entwicklers
lastName Nachname des Entwicklers
email E-Mail-Adresse des Entwicklers
status Status des Entwicklers als aktiv, inaktiv oder login_lock
apps Eine Reihe von Apps, die dem Entwickler zugeordnet sind.
created_at Das Datum/die Uhrzeit, zu der der Entwickler erstellt wurde.
created_by Die E-Mail-Adresse des Nutzers, der den Entwickler erstellt hat.
last_modified_at Der Datums-/Zeitstempel, zu dem der Entwickler zuletzt geändert wurde.
last_modified_by Die E-Mail-Adresse des Nutzers, der den Entwickler geändert hat.
{developer_custom_attributes} Alle benutzerdefinierten Entwicklerattribute. Geben Sie den Namen des benutzerdefinierten Attributs an.

Analytics-Variablen

Die folgenden Variablen werden in Analytics automatisch ausgefüllt, wenn eine gültige API-Schlüsselrichtlinie für einen gültigen API-Schlüssel erzwungen wird. Diese Variablen werden nur durch die Richtlinie "API-Schlüssel überprüfen" und die OAuth-Richtlinien ausgefüllt.

Die Variablen und Werte können als Dimensionen zum Erstellen von Analytics-Berichten verwendet werden, um Einblicke in die Verbrauchsmuster von Entwicklern und Apps zu erhalten.

  • apiproduct.name
  • developer.app.name
  • client_id
  • developer.id

Ablaufvariablen für die Monetarisierung

Nach der Authentifizierung des Nutzers prüft die VerifyAPIKey-Richtlinie alle veröffentlichten Tarifpakete, um festzustellen, ob und welche davon aktiv sind, basierend auf den Aktivierungs- und Ablaufzeiten. Wird ein aktives veröffentlichtes Tarifpaket gefunden, werden die folgenden Ablaufvariablen ausgefüllt:

Variable Beschreibung
mint.mintng_is_apiproduct_monetized true, wenn ein aktives veröffentlichtes Tarifpaket gefunden wird.
mint.mintng_rate_plan_id Tarifpaket-ID.
mint.rateplan_end_time_ms Ablaufzeit für das Tarifpaket. Beispiel: 1619433556408
mint.rateplan_start_time_ms Aktivierungszeit des Tarifpakets. Beispiel: 1618433956209

Fehlerreferenz

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

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
keymanagement.service.consumer_key_missing_api_product_association 400

The application credential is missing an API product association. Please associate the key's application with an API product. Note that this applies for all application types, such as developer apps and AppGroup apps.
keymanagement.service.DeveloperStatusNotActive 401

The developer who created the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive, any Developer Apps created by that developer are deactivated. An admin user with appropriate permissions (such as Organization Administrator) can change a developer's status in the following ways:
keymanagement.service.invalid_client-app_not_approved 401 The Developer App associated with the API key is revoked. A revoked app cannot access any API products and cannot invoke any API managed by Apigee. An org admin can change the status of a Developer App using the Apigee API. See Generate Key Pair or Update Developer App Status.
oauth.v2.FailedToResolveAPIKey 401 The policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (it cannot be resolved).
oauth.v2.InvalidApiKey 401 An API key was received by Apigee, but it is invalid. When Apigee looks up the key in its database, it must exactly match the one that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Controlling access to your APIs by registering apps.
oauth.v2.InvalidApiKeyForGivenResource 401 An API key was received by Apigee, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.

Deployment errors

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

Error name Cause
SpecifyValueOrRefApiKey The <APIKey> element does not have a value or key specified.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.VK-VerifyAPIKey.failed = true

Example error responses

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>