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
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 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-Edge-Flussvariable, die mit dem Wert eines Headers gefüllt wird, 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>
Edge füllt automatisch eine Reihe von Flussvariablen, wenn die Richtlinie zum Überprüfen von API-Schlüsseln für einen gültigen API-Schlüssel ausgeführt wird. 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.
Edge kennenlernen
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:
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
name |
Der interne Name der Richtlinie. Der Wert des Attributs Optional können Sie das Element |
– | Erforderlich |
continueOnError |
Legen Sie Legen Sie |
false | Optional |
enabled |
Setzen Sie den Wert auf Legen Sie |
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 |
---|---|
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 | NA |
---|---|
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 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:
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 einer gültigen Umgebung, Proxys und Ressourcen konfiguriert sind (abgeleitet aus der proxy.pathsuffix ). Eine Anleitung zum Einrichten von API-Produkten finden Sie unter Edge Management API zum Veröffentlichen von APIs verwenden. |
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 mit der App verknüpften API-Produkte enthält. |
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 |
Der 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 |
Der Anzeigename des Unternehmens. |
id |
ID des Unternehmens |
apps |
Ein Array, das die Liste der Unternehmens-Apps enthält. |
appOwnerStatus |
Der Status des App-Inhabers: „Aktiv“, „Inaktiv“ oder „Anmeldungssperre“.
|
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
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.
Fault code | HTTP status | Cause |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | The Company associated with the Developer App that has the API key you are using has an inactive status. When a Company's status is set to inactive, you cannot access the developers or apps associated with that Company. An org admin can change a Company's status using the management API. See Set the Status of a Company. |
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 Edge. An org admin can change the status of a Developer App using the management API. See Approve or Revoke Developer App. |
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 Edge, but it is invalid. When Edge looks up the key in its database, it must exactly match the on 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 Register apps and manage API keys. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | An API key was received by Edge, 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>