VerifyAPIKey-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie 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.

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-Edge-Flussvariable, die mit dem Wert eines übergebenen Abfrageparameters ausgefüllt wird. in der Clientanfrage.

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-Edge-Flussvariable, die mit dem Wert eines übergebenen Headers gefüllt wird. in der Clientanfrage.

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>

Edge füllt beim Ausführen des API-Schlüssels „Verify API Key“ automatisch einen Satz von Flussvariablen aus für einen gültigen API-Schlüssel. 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.

Lerne Edge

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

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

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 beim Ausführen der Richtlinie zum Überprüfen des API-Schlüssels 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"/>
</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:

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 Veraltet

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

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Präsenz Optional
Typ 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>

Schemas

Ablaufvariablen

Wenn eine Richtlinie zum Überprüfen des API-Schlüssels für einen gültigen API-Schlüssel erzwungen wird, füllt Edge einen Satz von Fluss aus Variablen. 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
  • Company
  • Analyse

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

ID der Entwickler-App, von der die Anfrage stammt.
developer.app.name Der App-Name der Entwickler-App, von der die Anfrage stammt.
developer.id

Die ID des Entwicklers, der 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 gültiger Umgebung, Proxys und Ressourcen (abgeleitet von proxy.pathsuffix). Eine Anleitung zum Einrichten von API-Produkten finden Sie unter Verwenden der Kante Management API in die Veröffentlichung von APIs ändern.

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:

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 App-Typ, entweder "Unternehmen" oder "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.

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:

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.
Company Der Name des Unternehmens, sofern vorhanden, das mit dem Entwickler verknüpft ist.

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:

Variable Beschreibung
name Name des Unternehmens
displayName Anzeigename des Unternehmens
id

ID des Unternehmens
apps Ein Array, das die Liste der Unternehmens-Apps enthält.
appOwnerStatus
Der Status des App-Inhabers als aktiv, inaktiv oder login_lock.
created_at Datum und Uhrzeit, zu der das Unternehmen erstellt wurde.
created_by Die E-Mail-Adresse des Nutzers, der das Unternehmen erstellt hat.
last_modified_at Der Datums-/Zeitstempel, zu dem das Unternehmen zuletzt geändert wurde.
last_modified_by Die E-Mail-Adresse des Nutzers, der das Unternehmen zuletzt geändert hat.
{company_custom_attributes} Alle benutzerdefinierten Unternehmens-Attribute. 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

Fehlerreferenz

Dieser Abschnitt beschreibt die Fehlercodes und Fehlermeldungen, die zurückgegeben werden, und 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
keymanagement.service.CompanyStatusNotActive 401 Das Unternehmen, das mit der Entwickler-App verknüpft ist, für die der von dir verwendete API-Schlüssel verwendet wird, hat einen inaktiv sein. Ist der Status eines Unternehmens auf inaktiv gesetzt, können Sie nicht auf die Entwickler oder Apps, die mit diesem Unternehmen verknüpft sind. Ein Administrator der Organisation kann den Status eines Unternehmens ändern mithilfe der Verwaltungs-API. Siehe Status festlegen eines Unternehmens.
keymanagement.service.DeveloperStatusNotActive 401

Der Entwickler, der die den verwendeten API-Schlüssel besitzende Entwickler-App erstellt hat, hat den Status "Inaktiv". Wird der Status eines App-Entwicklers auf "Inaktiv" gesetzt, werden alle von diesem Entwickler erstellten Entwickler-Apps deaktiviert. Ein Administrator mit entsprechenden Berechtigungen (z. B. ein Organisationsadministrator) kann den Status eines Entwicklers auf folgende Weise ändern:
keymanagement.service.invalid_client-app_not_approved 401 Die mit dem API-Schlüssel verknüpfte Entwickler-App wird widerrufen. Eine widerrufene App kann auf API-Produkte zugreifen und keine von Apigee Edge verwalteten APIs aufrufen können. Ein Administrator der Organisation kann den Status einer Entwickler-App mithilfe der Verwaltungs-API ändern Weitere Informationen finden Sie unter . Entwickler-App genehmigen oder widerrufen
oauth.v2.FailedToResolveAPIKey 401 Die Richtlinie erwartet, den API-Schlüssel in einer im <APIKey>-Element der Richtlinie angegebenen Variablen zu finden. Dieser Fehler tritt auf, wenn die erwartete Variable nicht existiert (die Aufgabe kann nicht aufgelöst werden).
oauth.v2.InvalidApiKey 401 Edge hat einen API-Schlüssel erhalten, er ist aber ungültig. Wenn Edge den Schlüssel in seiner -Datenbank muss genau mit der übereinstimmen, die in der Anfrage gesendet wurde. Wenn die API funktioniert hat, sorgen Sie dafür, dass der Schlüssel nicht neu generiert wurde. Wenn der Schlüssel neu generiert wurde, wird diese Fehlermeldung angezeigt, wenn Sie versuchen, den alten Schlüssel zu verwenden. Weitere Informationen finden Sie unter Apps registrieren und API verwalten Schlüssel.
oauth.v2.InvalidApiKeyForGivenResource 401 Edge hat einen API-Schlüssel erhalten, der gültig ist. aber nicht mit einem freigegebenen Schlüssel in der Entwickler-App, die über ein Produkt mit Ihrem API-Proxy verknüpft ist.

Bereitstellungsfehler

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

Fehlername Ursache
SpecifyValueOrRefApiKey Für das Element <APIKey> wurde kein Wert oder Schlüssel angegeben.

Fehlervariablen

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

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 Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. oauthV2.VK-VerifyAPIKey.failed = true

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