Sécuriser une API en exigeant des clés API

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

Consultez la documentation d' Apigee Edge.

Vidéo : visionnez cette courte vidéo pour une introduction à la sécurisation de votre API.

Points abordés

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :

  • Créer un proxy d'API qui nécessite une clé API
  • Créer un produit d'API, un développeur et une application de développeur
  • Appeler votre API avec une clé API

Il est important de protéger votre API contre tout accès non autorisé. Pour ce faire, vous pouvez utiliser des clés API.

Lorsqu'une application envoie une requête à un proxy d'API configuré pour valider une clé API, elle doit fournir une clé valide. Lors de l'exécution, la règle VerifyAPIKey vérifie que la clé API fournie :

  • est valide ;
  • n'a pas été révoquée ;
  • correspond à la clé API du produit d'API qui expose les ressources demandées.

Si la clé est valide, la requête est autorisée. Si elle n'est pas valide, la requête entraîne un échec d'autorisation.

Créer le proxy d'API

Apigee dans la console Cloud

  1. Dans la console Google Cloud , accédez à la page Développement de proxys > Proxys d'API.

    Accéder aux proxys d'API

  2. Sélectionnez votre organisation dans le sélecteur de projet du volet Google Cloud. Le nom de l'organisation est identique à celui de votre projet Google Cloud.
  3. Cliquez sur + Créer.
  4. Dans le volet Créer un proxy, sous Modèle de proxy, sélectionnez Proxy inverse (le plus courant). Un proxy inverse achemine le trafic entrant vers un service de backend.
  5. Configurez le proxy comme suit :
    Nom Valeur
    Proxy Name (Nom du proxy) helloworld_apikey
    Base Path (Chemin de base)

    /helloapikey

    Le chemin de base du projet fait partie de l'URL utilisée pour envoyer des requêtes au proxy d'API.
    Description hello world protected by API key
    Cible (API existante)

    http://mocktarget.apigee.net

    Cela définit l'URL cible qu'Apigee appelle sur une requête adressée au proxy d'API. Cette cible renvoie une réponse simple : Hello, Guest!.
  6. Cliquez sur Suivant.
  7. Déployer (facultatif). Laissez ces champs vides.
  8. Cliquez sur Créer.
  9. Apigee crée le proxy et affiche un résumé des détails du proxy dans le volet Récapitulatif du proxy.

UI classique

  1. Accédez à l'interface utilisateur d'Apigee et connectez-vous.
  2. Sélectionnez votre organisation dans le menu déroulant en haut à gauche de l'UI.

  3. Cliquez sur Develop > API Proxies (Développer > Proxys d'API) pour afficher la liste des proxys d'API.

  4. Cliquez sur Créer.
    Bouton "Créer un proxy"
  5. Dans l'assistant Créer un proxy, sélectionnez Proxy inverse (le plus courant).
  6. Configurez le proxy comme suit :
    Dans ce champ procédez comme suit
    Nom du proxy Saisissez : helloworld_apikey
    Chemin de base du projet

    Remplacez par : /helloapikey

    Le chemin de base du projet fait partie de l'URL utilisée pour envoyer des requêtes au proxy d'API.
    Description Saisissez : hello world protected by API key
    Cible (API existante)

    Saisissez : http://mocktarget.apigee.net

    Cela définit l'URL cible qu'Apigee appelle sur une requête adressée au proxy d'API. Cette cible renvoie une réponse simple : Hello, Guest!.
  7. Cliquez sur Suivant.
  8. Sur la page Common policies (Règles communes), sélectionnez API Key (Clé API). Cette option ajoute automatiquement deux règles à votre proxy d'API et crée un produit d'API nécessaire pour générer la clé API.
  9. Cliquez sur Suivant.
  10. Sur la page "Summary" (Résumé), assurez-vous qu'un environnement de déploiement est sélectionné, puis cliquez sur Create and deploy (Créer et déployer).
  11. Cliquez sur Edit proxy (Modifier le proxy) pour afficher la page "Overview" (Présentation) du proxy d'API.

Afficher les règles

Apigee dans la console Cloud

  1. Dans le volet Résumé du proxy du proxy helloworld_apikey, cliquez sur l'onglet Développer.
  2. Dans le menu Règles, cliquez sur Ajouter une règle.
  3. Dans le volet Créer une règle, sous Sécurité, sélectionnez Vérifier la clé API.
  4. Dans le volet Valider la clé API, renseignez les champs obligatoires des sections Nom et Nom à afficher en utilisant les valeurs suivantes :
    • Nom : saisissez un nom de règle. Exemple :VerifyAPIKey
    • Nom à afficher : saisissez le nom de la règle à utiliser dans l'interface utilisateur. Exemple :Verify API Key
  5. Cliquez sur Créer.
  6. Cliquez sur  pour ajouter une autre règle.
  7. Dans le volet Créer une règle, sous Médiation, sélectionnez Attribuer un message.
  8. Dans le volet Attribuer un message, renseignez les champs obligatoires des sections Nom et Nom à afficher à l'aide des valeurs suivantes :
    • Nom : saisissez un nom de règle. Exemple :AssignMessage
    • Nom à afficher : saisissez le nom de la règle à utiliser dans l'interface utilisateur. Exemple :Assign Message
  9. Cliquez sur Créer.
  10. L'élément <APIKey> du code XML ci-dessous spécifie l'emplacement de la clé API dans la requête entrante. Par défaut, la règle récupère la clé à partir d'un paramètre de requête nommé apikey dans la requête HTTP. 
    <APIKey ref="request.queryparam.apikey" />

    Le nom apikey est arbitraire et peut être n'importe quelle propriété contenant la clé API.

  11. Mettez à jour le contenu de la règle Assign Message en le remplaçant par ce qui suit : 
    12. <AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
  12. Ajoutez les règles VerifyApiKey et Remove Query Param apikey.
    1. Dans le menu Proxy endpoints (Points de terminaison du proxy), cliquez sur Preflow (PreFlow).
    2. Dans le volet Requête de l'éditeur visuel, cliquez sur Ajouter une étape de stratégie.
    3. Dans le volet Add policy step (Ajouter une étape de règle), sélectionnez Verify API Key (Vérifier la clé API).
    4. Cliquez sur Ajouter.
    5. Dans le volet Requête de l'éditeur visuel, cliquez sur Ajouter une étape de stratégie.
    6. Dans le volet Ajouter une étape de règle, sélectionnez Supprimer le paramètre de requête apikey.
    7. Cliquez sur Ajouter.
  13. Cliquez sur Enregistrer.
  14. Déployez votre proxy dans un environnement :
    1. Cliquez sur Déployer.
    2. Sélectionnez une révision et un environnement.
    3. Cliquez sur Déployer.
  15. Testez vos modifications en appelant l'API comme décrit dans Essayer d'appeler l'API.

UI classique

  1. Dans l'éditeur de proxy d'API, cliquez sur l'onglet Développer. Vous verrez que deux règles ont été ajoutées au flux de requêtes du proxy d'API :
    • Vérifier la clé API : vérifie l'appel d'API pour s'assurer qu'une clé API valide est présente (envoyée en tant que paramètre de requête).
    • Supprimer le paramètre de requête apikey : règle AssignMessage qui supprime la clé API une fois la vérification terminée, afin qu'elle ne soit pas transmise et exposée inutilement.

  2. Cliquez sur l'icône de la règle VerifyAPIKey dans la vue de flux, puis examinez la configuration XML de la règle dans la vue de code inférieure. L'élément <APIKey> indique à la règle où elle doit rechercher la clé API lors de l'appel. Par défaut, elle recherche la clé sous la forme d'un paramètre de requête appelé apikey dans la requête HTTP :

    <APIKey ref="request.queryparam.apikey" />

    Le nom apikey est arbitraire et peut être n'importe quelle propriété contenant la clé API.

Essayer d'appeler l'API

Au cours de cette étape, vous allez effectuer un appel d'API directement au service cible qui réussit, puis un appel infructueux au proxy d'API pour voir comment il est protégé par les règles.

  1. Opération réussie

    Dans un navigateur Web, accédez à l'adresse suivante. Le proxy d'API est configuré pour transférer la requête à ce service cible, mais vous allez l'appeler directement pour le moment :

    http://mocktarget.apigee.net

    Vous devriez obtenir cette réponse indiquant que l'opération a réussi : Hello, Guest!

  2. Échec

    Essayez maintenant d'appeler votre proxy d'API :

    curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

    où YOUR ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements. Consultez la page Rechercher le nom d'hôte du groupe d'environnements.

    Sans la règle VerifyAPIKey, cet appel fournirait la même réponse que l'appel précédent. Toutefois, dans ce cas, vous devriez obtenir le message d'erreur suivant :

    {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

    ce qui signifie que vous n'avez pas transmis de clé API valide (en tant que paramètre de requête).

Au cours des étapes suivantes, vous obtiendrez la clé API requise.

Ajouter un produit API

Apigee dans la console Cloud

Pour ajouter un produit API à l'aide de l'interface utilisateur Apigee, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Distribution > Produits d'API :

    Accéder aux produits d'API

  2. Cliquez sur +Create (Créer).
  3. Saisissez les détails du produit API.
    Champ Description
    Nom Nom interne du produit d'API. Ne spécifiez pas de caractères spéciaux dans le nom.
    Remarque : Vous ne pouvez pas modifier le nom une fois le produit d'API créé.
    Nom à afficher Nom à afficher du produit d'API. Le nom à afficher est utilisé dans l'UI et peut être modifié à tout moment. Si elle n'est pas spécifiée, la valeur Name est utilisée. Ce champ est renseigné automatiquement à l'aide de la valeur du champ Name (Nom). Vous pouvez modifier ou supprimer son contenu. Le nom à afficher peut contenir des caractères spéciaux.
    Description Description du produit API.
    Environnement Environnements auxquels le produit d'API autorise l'accès. Par exemple, test ou prod.
    Accès Sélectionnez Public.
    Approuver automatiquement les requêtes d'accès Activez l'approbation automatique des requêtes de clé pour ce produit d'API depuis n'importe quelle application.
    Quota Ignorez ce champ dans ce tutoriel.
    Champs d'application OAuth autorisés Ignorez ce champ dans ce tutoriel.
  4. Dans la section Opérations, cliquez sur Ajouter une opération.
  5. Dans le champ Proxy d'API, sélectionnez le proxy d'API que vous venez de créer.
  6. Dans le champ Chemin d'accès, saisissez "/". Ignorez les autres champs.
  7. Cliquez sur Enregistrer pour enregistrer l'opération.
  8. Cliquez sur Save (Enregistrer) pour enregistrer le produit d'API.

Pour en savoir plus sur l'ajout d'un produit d'API, consultez Créer un produit d'API.

UI classique

Pour ajouter un produit API à l'aide de l'interface utilisateur Apigee, procédez comme suit :

  1. Sélectionnez Publier > Produits API.
  2. Cliquez sur +Create (Créer).
  3. Saisissez les détails du produit API.
    Champ Description
    Nom Nom interne du produit d'API. Ne spécifiez pas de caractères spéciaux dans le nom.
    Remarque : Vous ne pouvez pas modifier le nom une fois le produit d'API créé.
    Nom à afficher Nom à afficher du produit d'API. Le nom à afficher est utilisé dans l'UI et peut être modifié à tout moment. S'il n'est pas spécifié, la valeur du champ "Nom" est utilisée. Ce champ est renseigné automatiquement à l'aide de la valeur du champ "Name". Vous pouvez modifier ou supprimer son contenu. Le nom à afficher peut contenir des caractères spéciaux.
    Description Description du produit API.
    Environnement Environnements auxquels le produit d'API autorise l'accès. Par exemple, test ou prod.
    Accès Sélectionnez Public.
    Approuver automatiquement les requêtes d'accès Activez l'approbation automatique des requêtes de clé pour ce produit d'API depuis n'importe quelle application.
    Quota Ignorez ce champ dans ce tutoriel.
    Champs d'application OAuth autorisés Ignorez ce champ dans ce tutoriel.
  4. Dans la section Opérations, cliquez sur AJOUTER UNE OPÉRATION.
  5. Dans le champ Proxy d'API, ajoutez le proxy d'API que vous venez de créer.
  6. Dans le champ "Chemin d'accès", saisissez "/". Ignorez les autres champs.
  7. Cliquez sur Save (Enregistrer) pour enregistrer l'opération.
  8. Cliquez sur Save (Enregistrer) pour enregistrer le produit d'API.

Ajouter un développeur et une application à votre organisation

Nous allons ensuite simuler le workflow d'un développeur qui s'inscrit pour utiliser vos API. Un développeur possède une ou plusieurs applications qui appellent vos API, et chaque application obtient une clé API unique. En tant que fournisseur d'API, vous bénéficiez d'un contrôle plus précis de l'accès à vos API et de rapports plus détaillés sur le trafic des API par application.

Créer un développeur

Apigee dans la console Cloud

Pour créer un développeur, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Distribution > Développeurs :

    Accéder à Developers

  2. Cliquez sur + Créer.
  3. Saisissez les informations suivantes dans la fenêtre Ajouter un développeur :
    Champ Valeur
    Prénom Keyser
    Nom Soze
    E-mail keyser@example.com
    Username (Nom d'utilisateur) keyser
  4. Cliquez sur Ajouter.

Pour en savoir plus sur la création d'un développeur, consultez Enregistrer des développeurs d'applications.

UI classique

Pour créer un développeur, procédez comme suit :

  1. Sélectionnez Publier > Développeurs dans le menu.
    Remarque : Si vous êtes toujours dans l'écran "Développer", cliquez sur "<" à côté de DÉVELOPPER pour afficher le menu et sélectionnez Publier > Développeurs
  2. Cliquez sur + Développeur.
  3. Saisissez les informations suivantes dans la fenêtre "Nouveau développeur" :
    Dans ce champ entrée
    Prénom Keyser
    Nom Soze
    Nom d'utilisateur keyser
    E-mail keyser@example.com
  4. Cliquez sur Créer.

Enregistrer une application

Apigee dans la console Cloud

  1. Dans la console Google Cloud , accédez à la page Distribution > Applications :

    Accédez à "Applications".

  2. Cliquez sur + Créer.
  3. Saisissez les informations suivantes dans la fenêtre Créer une application :
    Champ Valeur
    Nom de l'application Saisissez : keyser_app
    Nom à afficher Saisissez : keyser_app
    Developer Sélectionnez : Keyser Soze (keyser@example.com).
    URL de rappel Laissez le champ vide
    Remarques Laissez le champ vide
  4. Dans la section "Identifiants", cliquez sur Ajouter un identifiant.
  5. Sélectionnez Jamais. Les identifiants de cette application n'expirent jamais.
  6. Cliquez sur Ajouter des produits.
  7. Sélectionnez le produit que vous venez de créer.
  8. Cliquez sur Ajouter.
  9. Cliquez sur Créer.

Pour en savoir plus sur l'enregistrement d'une application, consultez Enregistrer une application.

UI classique

Pour enregistrer une application de développeur, procédez comme suit :

  1. Sélectionnez Publier > Applications.
  2. Cliquez sur + App (+ Application).
  3. Saisissez les informations suivantes dans la fenêtre "Nouvelle application de développeur" :
    Champ Valeur
    Nom et Nom à afficher Saisissez : keyser_app
    Developer Sélectionnez : Keyser Soze (keyser@example.com).
    URL de rappel et Remarques Laissez le champ vide
  4. Dans la section "Credentials" (Identifiants), sélectionnez Never (Jamais). Les identifiants de cette application n'expirent jamais.
  5. Cliquez sur Ajouter un produit.
  6. Sélectionnez le produit que vous venez de créer.
  7. Cliquez sur Créer.

Obtenir la clé API

Apigee dans la console Cloud

Pour obtenir la clé API, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Distribution > Applications.

    Accédez à "Applications".

  2. Sélectionnez l'application requise dans la liste des applications.
  3. Sur la page Afficher l'application, sous Identifiants, cliquez sur à côté du champ Clé. Notez que la clé est associée au produit que vous avez créé.
  4. Cliquez sur  Copier. Vous utiliserez cette clé à l'étape suivante.

UI classique

Pour obtenir la clé API, procédez comme suit :

  1. Sur la page "Applications" (Publier > Applications), cliquez sur keyser_app.
  2. Sur la page keyser_app, cliquez sur Show (Afficher) à côté de Key (Clé) dans la section Credentials (Identifiants). Notez que la clé est associée au produit que vous avez créé.
  3. Sélectionnez et copiez la clé. Vous l'utiliserez à l'étape suivante.

Appeler l'API avec une clé

Maintenant que vous disposez d'une clé API, vous pouvez l'utiliser pour appeler le proxy d'API. Collez la clé API comme indiqué, en tant que paramètre de requête. Assurez-vous que le paramètre de requête ne comporte aucun espace supplémentaire.

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=YOUR_API_KEY

Désormais, lorsque vous appelez le proxy d'API, vous obtenez la réponse suivante : Hello, Guest!

Félicitations ! Vous avez créé un proxy d'API et l'avez protégé en exigeant qu'une clé API valide soit incluse dans l'appel.

Notez qu'il n'est généralement pas recommandé de transmettre une clé API en tant que paramètre de requête. Vous devriez plutôt envisager de la transmettre dans l'en-tête HTTP.

Bonne pratique : transmettre la clé dans l'en-tête HTTP

Au cours de cette étape, vous allez modifier le proxy pour rechercher la clé API dans un en-tête nommé x-apikey.

Apigee dans la console Cloud

  1. Dans la console Google Cloud , accédez à la page Développement de proxys > Proxys d'API.

    2. Accéder aux proxys d'API

  2. Sélectionnez le proxy requis dans la liste des proxys.
  3. Sur la page Détails du proxy, cliquez sur Développer.
  4. Modifiez le code XML de la règle pour lui indiquer de rechercher la clé API dans l'en-tête plutôt que dans le paramètre de requête :
    5. <APIKey ref="request.header.x-apikey"/>
  5. Cliquez sur Enregistrer afin d'enregistrer les modifications.
  6. Cliquez sur Déployer.
  7. Sélectionnez une révision et un environnement.
  8. Cliquez sur Déployer.

  9. Effectuez l'appel d'API suivant en utilisant cURL pour transmettre la clé API en tant qu'en-tête nommé x-apikey. N'oubliez pas de remplacer le nom de votre organisation.

    curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Notez que pour finaliser la modification, vous devez également configurer la règle AssignMessage pour supprimer l'en-tête et non le paramètre de requête. Exemple :

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

UI classique

  1. Modifiez le proxy d'API. Sélectionnez Développer > Proxys d'API > helloworld_apikey, puis accédez à la vue Développer.

  2. Sélectionnez la règle VerifyAPIKey, puis modifiez son code XML pour lui indiquer de rechercher la clé API dans header plutôt que dans queryparam :

    <APIKey ref="request.header.x-apikey"/>
  3. Enregistrez le proxy d'API, puis utilisez Déployer.

  4. Effectuez l'appel d'API suivant en utilisant cURL pour transmettre la clé API en tant qu'en-tête nommé x-apikey. N'oubliez pas de remplacer le nom de votre organisation.

    curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Notez que pour finaliser la modification, vous devez également configurer la règle AssignMessage pour supprimer l'en-tête et non le paramètre de requête. Exemple :

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

Articles associés

Voici quelques articles liés aux produits et clés API :

La protection des API implique souvent une sécurité supplémentaire telle que OAuth, un protocole ouvert qui échange des identifiants (nom d'utilisateur et mot de passe, par exemple) contre des jetons d'accès. Les jetons d'accès sont de longues chaînes aléatoires qui peuvent être transmises via un pipeline de messages, y compris d'une application à une autre, sans compromettre les identifiants d'origine.

Pour obtenir une présentation des sujets liés à la sécurité, consultez la page Sécuriser un proxy.