VerifyAPIKey-Richtlinie

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

Was

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.

Samples

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

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

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

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

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

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

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

verifyapikey.{policy_name}

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

Wenn ein Entwickler eine App auf Edge registriert, generiert Edge automatisch ein Consumer-Key-Secret-Paar. Sie können das Consumer-Key-Secret-Paar der Anwendung in der Edge-Benutzeroberfläche sehen oder über die Edge 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.

Edge füllt automatisch eine Reihe von Flussvariablen, wenn die Richtlinie zum Überprüfen von API-Schlüsseln ausgeführt wird. 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"/>
</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">

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>

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

Attribute

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

Beispiele

In diesen Beispielen werden der Schlüssel in Parametern und einem Header namens 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>

Schemas

Ablaufvariablen

Wenn eine Richtlinie zum Überprüfen von API-Schlüsseln für einen gültigen API-Schlüssel erzwungen wird, füllt Edge eine Reihe von Flussvariablen aus. 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
• Unternehmen
• Analytics

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:

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.

Beispiel:

verifyapikey.{policy_name}.app.name

Folgende Variablen sind verfügbar:

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

Beispiel:

verifyapikey.{policy_name}.developer.id

Folgende Variablen sind verfügbar:

Unternehmens-Ablaufvariablen

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

verifyapikey.{policy_name}.company

Beispiel:

verifyapikey.{policy_name}.company.name

Folgende Variablen sind verfügbar:

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

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.

Bereitstellungsfehler

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

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Beispiele für Fehlerantworten

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

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

Beispiel für eine Fehlerregel

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

Weitere Informationen