Règle VerifyAPIKey

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

icône de la règle

Présentation

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.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Pour suivre un tutoriel sur la création d'un proxy d'API à l'aide de la règle de vérification des clés API, consultez la page Sécuriser une API en exigeant des clés API.

Exemples

Clé dans le paramètre de requête

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

Dans cet exemple, la règle s'attend à trouver la clé API dans une variable de flux appelée request.queryparam.apikey. La variable request.queryparam.{name} est une variable de flux Apigee standard renseignée avec la valeur d'un paramètre de requête transmis dans la requête client.

La commande curl suivante transmet la clé API dans un paramètre de requête :

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

Clé dans l'en-tête

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

Dans cet exemple, la règle s'attend à trouver la clé API dans une variable de flux appelée request.header.x-apikey. La variable request.header.{name} est une variable de flux Apigee standard renseignée avec la valeur d'un en-tête transmis dans la requête client.

La commande cURL suivante montre comment transmettre la clé API dans un en-tête :

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

Clé dans la variable

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

La clé peut référencer toute variable contenant la clé. La règle de cet exemple extrait la clé API d'une variable nommée requestAPIKey.key.

C'est à vous de décider comment la variable est renseignée. Par exemple, vous pouvez utiliser la règle Extract Variables pour renseigner requestAPIKey.key à partir d'un paramètre de requête nommé myKey, comme illustré ci-dessous :

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

Règle d'accès pour les variables de flux

<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 renseigne automatiquement un ensemble de variables de flux lors de l'exécution de la règle de vérification des clés API pour une clé API valide. Vous pouvez utiliser ces variables pour accéder à des informations telles que le nom de l'application, l'ID de l'application, et des informations sur le développeur ou l'entreprise qui a enregistré l'application. Dans l'exemple ci-dessus, vous utilisez la règle d'attribution des messages pour accéder au prénom, au nom et à l'adresse e-mail du développeur après l'exécution de la vérification des clés API.

Ces variables ont toutes le préfixe :

verifyapikey.{policy_name}

Dans cet exemple, le nom de la règle de vérification des clés API est "verify-api-key". Par conséquent, vous référencez le prénom du développeur à l'origine de la requête en accédant à la variable verifyapikey.verify-api-key.developer.firstName..

Découvrir Apigee

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

Lorsqu'un développeur enregistre une application sur Apigee, Apigee génère automatiquement une paire clé/secret client. Vous pouvez voir la paire clé/secret client de l'application dans l'interface utilisateur d'Apigee ou y accéder depuis l'API Apigee.

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.

Apigee renseigne automatiquement un ensemble de variables de flux lors de l'exécution de la règle de vérification des clés 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"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</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 :

Attribut Description Par défaut Presence
name

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

 N/A Obligatoire
continueOnError

Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également :

 false Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

 true Facultatif
async

Cet attribut est obsolète.

 false Obsolète

É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>
Par défaut

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Presence Facultatif
Type Chaîne

É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

Par défaut NA
Presence Obligatoire
Type Chaîne

Attributs

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

Attribut Description Par défaut Presence
ref

Référence à la variable contenant la clé API. Un seul emplacement est autorisé par règle.

 ND Obligatoire

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>

Élément <CacheExpiryInSeconds>

Cet élément applique la valeur TTL sur le cache, ce qui permet de personnaliser la période d'expiration du jeton d'accès mis en cache. La plage acceptée est comprise entre 1 et 180 secondes. Vous pouvez fournir une variable de flux et une variable par défaut. Si elle est fournie, la valeur de la variable de flux est prioritaire sur la valeur par défaut spécifiée. 

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
Par défaut N/A

Si vous omettez cet élément, le délai d'expiration par défaut du jeton d'accès mis en cache est de 180 secondes.
Presence Facultatif
Type Entier
Valeurs valides Tout entier positif non nul. Indique le délai d'expiration, en secondes.

Attributs

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

Attribut Description Par défaut Presence
ref

Référence à la variable de flux contenant la valeur d'expiration du cache, exprimée en secondes.

Si elle est fournie, la valeur de la variable de flux est prioritaire sur la valeur par défaut spécifiée.

 ND Facultatif

Schémas

Variables de flux

Lorsqu'une règle de vérification des clés API est appliquée à une clé API valide, Apigee renseigne un ensemble de variables de flux. 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
  • Analyse
  • Monétisation

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 :

Variable Description
client_id Clé client (également appelée clé API ou clé d'application) fournie par l'application à l'origine de la requête.
client_secret Secret client associé à la clé client.
redirection_uris Tout URI de redirection dans la requête.
developer.app.id

ID du développeur ou de l'application AppGroup à l'origine de la requête.
developer.app.name Nom de l'application du développeur ou de l'application AppGroup à l'origine de la requête.
developer.id

ID du développeur ou AppGroup enregistré en tant que propriétaire de l'application à l'origine de la requête.
developer.{custom_attrib_name} Tous les attributs personnalisés dérivés du profil de clé d'application.
DisplayName Valeur de l'attribut <DisplayName> de la règle.
failed Défini sur "true" en cas d'échec de la validation de clé API.
{custom_app_attrib} Tout attribut personnalisé dérivé du profil de l'application Spécifie le nom de l'attribut personnalisé.
apiproduct.name* Nom du produit d'API utilisé pour valider la requête.
apiproduct.{custom_attrib_name}* Tout attribut personnalisé dérivé du profil de produit d'API.
apiproduct.developer.quota.limit* Limite de quota définie sur le produit d'API, le cas échéant.
apiproduct.developer.quota.interval* Intervalle de quota défini sur le produit d'API, le cas échéant.
apiproduct.developer.quota.timeunit* Unité de temps du quota défini sur le produit d'API, le cas échéant.
* Les variables de produit d'API sont automatiquement renseignées si les produits d'API sont configurés avec un environnement, des proxys et des ressources valides (dérivés de proxy.pathsuffix). Pour obtenir des instructions sur la configuration des produits d'API, consultez la page Gérer des produits d'API.

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 :

Variable Description
name Nom de l'application.
id ID de l'application.
accessType Non utilisé par Apigee.
callbackUrl URL de rappel de l'application. En général utilisé uniquement pour OAuth.
DisplayName Nom à afficher de l'application.
status État de l'application, tel que "approuvé" ou "révoqué".
apiproducts Tableau contenant la liste des produits d'API associés à l'application.
appFamily Toute famille d'applications contenant l'application, ou "par défaut".
appParentStatus État du parent de l'application, tel que "actif" ou "inactive".
appType Type d'application, tel que "Développeur".
appParentId ID de l'application parente.
created_at Date et heure de création de l'application.
created_by Adresse e-mail du développeur qui a créé l'application.
last_modified_at Date et heure de la dernière mise à jour de l'application.
last_modified_by Adresse e-mail du développeur qui a mis à jour l'application pour la dernière fois.
{app_custom_attributes} Tout attribut d'application personnalisé. Spécifie le nom de l'attribut personnalisé.

Variables de flux AppGroup

Les variables de flux suivantes contenant des informations sur les AppGroups sont renseignées par la règle. Ces attributs AppGroup ne sont renseignés que si verifyapikey.{policy_name}.app.appType est "AppGroup".

Ces variables ont toutes le préfixe :

verifyapikey.{policy_name}.appgroup.

Exemple :

verifyapikey.{policy_name}.appgroup.name

Les variables disponibles sont les suivantes :

Variable Description
name Nom de l'AppGroup.
id ID de l'AppGroup.
displayName Nom à afficher de l'AppGroup.
appOwnerStatus État du propriétaire de l'application : "active", "inactive" ou "login_lock".
created_at Date et heure de création de l'AppGroup.
created_by Adresse e-mail du développeur qui a créé l'AppGroup.
last_modified_at Date et heure de la dernière modification de l'AppGroup.
last_modified_by Adresse e-mail du développeur qui a modifié l'AppGroup pour la dernière fois.
{appgroup_custom_attributes} Tout attribut AppGroup personnalisé. Spécifie le nom de l'attribut personnalisé.

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 :

Variable Description
id Renvoie {org_name}@@@{developer_id}.
userName Nom d'utilisateur du développeur.
firstName Prénom du développeur.
lastName Nom du développeur.
email Adresse e-mail du développeur.
status État du développeur (actif, inactif ou login_lock).
apps Tableau des applications associées au développeur.
created_at Date et heure de création du développeur.
created_by Adresse e-mail de l'utilisateur qui a créé le développeur.
last_modified_at Date et heure de la dernière modification du développeur.
last_modified_by Adresse e-mail de l'utilisateur qui a modifié le développeur.
{developer_custom_attributes} Tout attribut de développeur personnalisé. Spécifie le nom de l'attribut personnalisé.

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

Variables de flux de monétisation

Après l'authentification de l'utilisateur, la règle VerifyAPIKey vérifie tous les plans tarifaires publiés pour déterminer, le cas échéant, lequel est actif en fonction de leurs délais d'activation et d'expiration. Si un plan tarifaire actif est détecté, les variables de flux suivantes sont renseignées :

Variable Description
mint.mintng_is_apiproduct_monetized true si un plan tarifaire publié actif est détecté.
mint.mintng_rate_plan_id Identifiant du plan tarifaire.
mint.rateplan_end_time_ms Délai d'expiration du plan tarifaire. Par exemple : 1619433556408
mint.rateplan_start_time_ms Heure d'activation du plan tarifaire. Par exemple : 1618433956209

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle 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.

Code d'erreur État HTTP Cause
keymanagement.service.consumer_key_missing_api_product_association 400

Les identifiants de l'application ne sont pas associés à un produit d'API. Veuillez associer l'application de la clé à un produit d'API. Notez que cela s'applique à tous les types d'applications, tels que les applications de développeur et les applications AppGroup.
keymanagement.service.DeveloperStatusNotActive 401

Le développeur ayant créé l'application de développeur disposant de la clé API que vous utilisez est à l'état "inactif". Lorsque l'état d'un développeur d'applications est défini sur "inactif", toutes les applications de développeur créées par ce développeur sont désactivées. Un administrateur disposant des autorisations appropriées (par exemple, administrateur de l'organisation) peut modifier l'état d'un développeur de différentes manières :
keymanagement.service.invalid_client-app_not_approved 401 L'application de développeur associée à la clé API est révoquée. Une application révoquée ne peut accéder à aucun produit d'API et ne peut pas appeler n'importe quelle API gérée par Apigee. Un administrateur d'organisation peut modifier l'état d'une application de développeur à l'aide de l'API Apigee. Consultez la section generateKeyPairOrUpdateDeveloperAppStatus.
oauth.v2.FailedToResolveAPIKey 401 La règle s'attend à trouver la clé API dans une variable spécifiée dans l'élément <APIKey> de la règle. Cette erreur se produit lorsque la variable attendue n'existe pas (elle ne peut pas être résolue).
oauth.v2.InvalidApiKey 401 Une clé API a été reçue par Apigee, mais elle n'est pas valide. Lorsque Apigee recherche la clé dans sa base de données, elle doit correspondre exactement à celle qui a été envoyée dans la requête. Si l'API a fonctionné précédemment, assurez-vous que la clé n'a pas été générée de nouveau. Si la clé a été regénérée, cette erreur s'affiche si vous essayez d'utiliser l'ancienne clé. Pour plus d'informations, consultez la section Contrôler l'accès à vos API en enregistrant des applications.
oauth.v2.InvalidApiKeyForGivenResource 401 Une clé API a été reçue par Apigee et elle est valide. Toutefois, elle ne correspond pas à une clé approuvée dans l'application de développement associée à votre proxy d'API via un Produit.

Erreurs de déploiement

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

Nom de l'erreur Cause
SpecifyValueOrRefApiKey Aucune valeur ou clé n'est spécifiée pour l'élément <APIKey>.

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.

Variables Lieu Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. oauthV2.VK-VerifyAPIKey.failed = true

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>