Règle VerifyAPIKey

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Quoi

La règle de vérification des clés API vous permet d'appliquer la validation des clés API lors de l'exécution, afin de n'autoriser que les applications disposant de clés API approuvées à accéder à vos API. Cette règle garantit que les clés API sont valides, n'ont pas été révoquées et qu'elles sont autorisées à consommer les ressources spécifiques associées à vos produits d'API.

Exemples

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

À propos de la stratégie Vérifier la clé API

Lorsqu'un développeur enregistre une application sur Edge, Edge génère automatiquement une clé client et par paire secrète. Vous pouvez voir la clé client et la paire secrète de l'application dans l'interface utilisateur Edge ou y accéder de l'API Edge.

Au moment de l'enregistrement de l'application, le développeur sélectionne un ou plusieurs produits d'API à associer à l'application, où un produit d'API est un ensemble de ressources accessibles via des proxys d'API. Le développeur transmet ensuite la clé API (clé client) dans toutes les requêtes à une API dans un produit d'API associé à l'application. Consultez la section Présentation du processus de publication pour en savoir plus.

Les clés API peuvent être utilisées comme jetons d'authentification, ou pour obtenir des jetons d'accès OAuth. Dans OAuth, les clés API sont appelées "ID client". Les noms peuvent être utilisés de manière interchangeable. Pour en savoir plus, consultez la Page d'accueil OAuth.

Edge renseigne automatiquement un ensemble de variables de flux lors de l'exécution de la stratégie Vérifier la clé API. Consultez la section Variables de flux ci-dessous pour en savoir plus.

Documentation de référence des éléments

Vous trouverez ci-dessous les éléments et les attributs que vous pouvez configurer sur cette règle :

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

Attributs <VerifyAPIKey>

L'exemple suivant montre les attributs du tag <VerifyAPIKey> :

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

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Élément <APIKey>

Cet élément spécifie la variable de flux contenant la clé API. En règle générale, le client envoie la clé API dans un paramètre de requête, un en-tête HTTP ou un paramètre de formulaire. Par exemple, si la clé est envoyée dans un en-tête nommé x-apikey, la clé apparaît dans la variable : request.header.x-apikey

Attributs

Le tableau suivant décrit les attributs de l'élément <APIKey>

Exemples

Dans ces exemples, la clé est transmise dans les paramètres et un en-tête appelé x-apikey.

En tant que paramètre de requête :

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

En tant qu'en-tête HTTP :

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

En tant que paramètre de formulaire HTTP :

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

Schémas

Variables de flux

Lorsqu'une règle Vérifier la clé API est appliquée à une clé API valide, Edge remplit un ensemble de flux variables. Ces variables sont disponibles pour les règles ou le code exécutés plus tard dans le flux, et sont souvent utilisées pour effectuer un traitement personnalisé en fonction des attributs de la clé API, tels que le nom de l'application, le produit d'API utilisé pour autoriser la clé, ou les attributs personnalisés de la clé API.

La règle insère plusieurs types de variables de flux, y compris les suivants :

• Général
• Application
• Développeur
• Société
• Analyse

Chaque type de variable de flux comporte un préfixe différent. Toutes les variables sont des valeurs scalaires, hormis celles spécifiquement désignées comme tableaux.

Variables de flux générales

Le tableau suivant répertorie les variables de flux générales renseignées par la règle de vérification des clés API. Ces variables ont toutes le préfixe :

verifyapikey.{policy_name}

Par exemple : verifyapikey.{policy_name}.client_id

Les variables disponibles sont les suivantes :

Variables de flux d'application

Les variables de flux suivantes contenant des informations sur l'application sont renseignées par la règle. Ces variables ont toutes le préfixe :

verifyapikey.{policy_name}.app.

Exemple :

verifyapikey.{policy_name}.app.name

Les variables disponibles sont les suivantes :

Variables de flux de développeur

Les variables de flux suivantes contenant des informations sur le développeur sont renseignées par la règle. Ces variables ont toutes le préfixe :

verifyapikey.{policy_name}.developer

Exemple :

verifyapikey.{policy_name}.developer.id

Les variables disponibles sont les suivantes :

Variables de flux de l'entreprise

Les variables de flux suivantes contenant des informations sur l'entreprise sont renseignées par la règle. Ces variables ont toutes le préfixe :

verifyapikey.{policy_name}.company

Exemple :

verifyapikey.{policy_name}.company.name

Les variables disponibles sont les suivantes :

Variables de données analytiques

Les variables suivantes sont automatiquement renseignées dans Analytics lorsqu'une règle de vérification des clés API est appliquée pour une clé API valide. Ces variables ne sont renseignées que par la règle de vérification des clés API et les règles OAuth.

Les variables et valeurs peuvent être utilisées comme dimensions pour créer des rapports Analytics et permettre plus de visibilité sur les modèles de consommation par les développeurs et les applications.

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

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur qui sont renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponses d'erreur

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

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

Exemple de règle de défaillance

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

Articles associés