Restreindre l'accès à l'API avec des clés API

OpenAPI | gRPC

Les clés API vous permettent de restreindre l'accès à certaines méthodes d'une API ou à l'ensemble de ses méthodes. Cette page explique comment restreindre l'accès à une API aux seuls clients disposant de la clé API correspondante, ainsi que comment créer une clé API.

Le proxy Extensible Service Proxy (ESP) utilise l'API Service Control pour valider une clé API et son association avec une API active d'un projet. Si vous configurez une exigence de clé API dans votre API, toute requête concernant la méthode, la classe ou l'API ainsi protégées est rejetée, sauf si elle est assortie d'une clé générée au sein de votre projet ou dans un autre projet appartenant à un développeur auquel vous avez donné l'autorisation d'activer cette API. Le projet dans lequel la clé API a été créée n'est ni consigné, ni ajouté à l'en-tête de requête. Toutefois, vous pouvez afficher le Google Cloud projet auquel un client est associé dans Endpoints > Services, comme décrit dans la section Filtrer un projet pour un consommateur spécifique.

Pour plus d'informations sur le Google Cloud projet dans lequel une clé API doit être créée dans, consultez la section Partager des API protégées par une clé API.

Restreindre l'accès à toutes les méthodes d'une API

Si vous souhaitez qu'une clé API soit exigée pour accéder à toutes les méthodes d'une API :

OpenAPI 2.0

1. Ouvrez le fichier openapi.yaml de votre projet dans un éditeur de texte.
2. Sous securityDefinitions:, ajoutez les valeurs apiKey, key et query de api_key: comme indiqué dans l'exemple d'extrait de code ci-dessous :
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

   Cela établit un "schéma de sécurité" appelé api_key que vous pouvez utiliser pour protéger l'API. Pour en savoir plus sur les autres options de définition api_key, consultez la section Limites de définition de clé d'API.

3. En haut du fichier (il ne doit pas être en retrait ni imbriqué), ajoutez api_key: [] à la directive security. Vous devrez peut-être ajouter la directive security ou elle sera peut-être déjà présente :

   security:
     - api_key: []

   Cette directive applique le schéma de sécurité api_key à toutes les méthodes du fichier. Ne placez rien dans les crochets. La spécification OpenAPI nécessite une liste vide pour les schémas de sécurité qui n'utilisent pas l'authentification OAuth.

OpenAPI 3.x

1. Ouvrez le fichier openapi.yaml de votre projet dans un éditeur de texte.
2. Sous components.securitySchemes:, ajoutez les éléments suivants :

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   Cela établit un "schéma de sécurité" appelé api_key que vous pouvez utiliser pour protéger l'API.

3. En haut du fichier (il ne doit pas être en retrait ni imbriqué), ajoutez api_key: [] à la directive security :

   security:
     - api_key: []

   Cette directive applique le schéma de sécurité api_key à toutes les méthodes du fichier.

Restreindre l'accès à certaines méthodes de l'API

Si vous souhaitez qu'une clé API soit exigée pour une méthode spécifique :

OpenAPI 2.0

1. Ouvrez le fichier openapi.yaml de votre projet dans un éditeur de texte.
2. En haut du fichier (il ne doit pas être en retrait ni imbriqué), ajoutez une directive de sécurité vide pour l'appliquer à l'ensemble de l'API :

   security: []

3. Sous securityDefinitions:, ajoutez les valeurs apiKey, key et query de api_key: comme indiqué dans l'exemple d'extrait de code ci-dessous :
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

   Cela établit un "schéma de sécurité" appelé api_key que vous pouvez utiliser pour protéger l'API. Pour en savoir plus sur les autres options de définition api_key, consultez la section Limites de définition de clé d'API.

4. Ajoutez api_key: [] à la directive security dans la définition de la méthode :

   ...
   paths:
     "/echo":
       post:
         description: "Echo back a given message."
         operationId: "echo"
         security:
         - api_key: []
         produces:
         ...

   Cette directive applique le schéma de sécurité api_key à la méthode. Ne placez rien dans les crochets. La spécification OpenAPI nécessite une liste vide pour les schémas de sécurité qui n'utilisent pas l'authentification OAuth.

OpenAPI 3.x

1. Ouvrez le fichier openapi.yaml de votre projet dans un éditeur de texte.
2. En haut du fichier (il ne doit pas être en retrait ni imbriqué), ajoutez une directive de sécurité vide pour l'appliquer à l'ensemble de l'API :

   security: []

3. Sous components.securitySchemes:, ajoutez les éléments suivants :

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   Cela établit un "schéma de sécurité" appelé api_key que vous pouvez utiliser pour protéger l'API.

4. Ajoutez api_key: [] à la directive security dans la définition de la méthode :

   ...
   paths:
     /echo:
       post:
         description: "Echo back a given message."
         operationId: "echo"
         security:
         - api_key: []
         requestBody:
         ...

   Cette directive applique le schéma de sécurité api_key à la méthode.

Supprimer la restriction de clé API pour une méthode

Pour désactiver la validation de clé API pour une méthode particulière même lorsque vous avez restreint l'accès à l'API pour l'API :

OpenAPI 2.0

1. Ouvrez le fichier openapi.yaml de votre projet dans un éditeur de texte.
2. Ajoutez une directive security vide dans la définition de la méthode :

     ...
     paths:
       "/echo":
         post:
           description: "Echo back a given message."
           operationId: "echo"
           security: []
           produces:
           ...

OpenAPI 3.x

1. Ouvrez le fichier openapi.yaml de votre projet dans un éditeur de texte.
2. Ajoutez une directive security dans la définition de la méthode :

     ...
     paths:
       /echo:
         post:
           description: "Echo back a given message."
           operationId: "echo"
           security: []
           requestBody:
           ...

Appeler une API à l'aide d'une clé API

Si une API ou une méthode d'API nécessite une clé API, fournissez la clé à l'aide d'un paramètre de requête nommé key, comme indiqué dans cet exemple curl :

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

où ENDPOINTS_HOST et ENDPOINTS_KEY sont des variables d'environnement contenant le nom d'hôte de votre API et votre clé API, respectivement.

Partager des API protégées par une clé API

Les clés API sont associées au Google Cloud projet dans lequel elles ont été créées. Si vous avez décidé de demander une clé API à votre API, le Google Cloud projet dans lequel la clé API est créée dépend des réponses aux questions suivantes :

• Avez-vous besoin de distinguer les appelants de votre API pour pouvoir utiliser les fonctionnalités Endpoints comme les quotas ?
• Tous les appelants de votre API ont-ils leur propre Google Cloud projet ?
• Avez-vous besoin de configurer différentes restrictions de clés API?

L'arbre de décision suivant peut vous servir de guide pour choisir le Google Cloud projet dans lequel créer la clé API.

Accorder l'autorisation d'activer l'API

Lorsque vous devez faire la distinction entre les appelants de votre API et que chaque appelant dispose de son propre Google Cloud projet, vous pouvez autoriser les comptes principaux à activer l'API dans leur propre Google Cloud projet. De cette manière, les utilisateurs de votre API peuvent créer leur propre clé API à utiliser avec votre API.

Par exemple, supposons que votre équipe ait créé une API à usage interne pour différents programmes clients de votre entreprise et que chaque programme client possède son propre Google Cloud projet. Pour distinguer les appelants de votre API, la clé API de chaque appelant doit être créée dans un Google Cloud projet différent. Vous pouvez accorder à vos collègues l'autorisation d'activer l'API dans le Google Cloud projet auquel le programme client est associé.

Pour permettre aux utilisateurs de créer leur propre clé API :

1. Dans le Google Cloud projet dans lequel votre API est configurée, accordez à chaque utilisateur l' autorisation d'activer votre API.
2. Contactez les utilisateurs et faites-leur savoir qu'ils peuvent activer votre API dans leur propre Google Cloud projet et créer une clé API.

Créer un Google Cloud projet distinct pour chaque appelant

Lorsque vous devez faire la distinction entre les appelants de votre API et que les appelants n'ont pas tous de projet, vous pouvez créer un Google Cloud projet et une Google Cloud clé API distincts pour chaque appelant. Avant de créer ces projets, réfléchissez aux noms que vous allez leur donner, afin d'être en mesure d'identifier facilement l'appelant associé à chaque projet.

Par exemple, supposons que vous ayez des clients externes pour votre API, et que vous ne sachiez pas comment les programmes clients qui appellent celle-ci ont été créés. Certains clients utilisent peut-être des Google Cloud services et possèdent donc un Google Cloud projet, alors que d'autres non. Pour distinguer les appelants, vous devez créer un projet et une clé API distincts Google Cloud pour chacun d'eux.

Pour créer un Google Cloud projet et une clé API distincts pour chaque appelant :

1. Créez un projet distinct pour chaque appelant.
2. Dans chaque projet, activez votre API et créez une clé API.
3. Donnez la clé API à chaque appelant.

Créer une clé API pour chaque appelant

Lorsque vous n'avez pas besoin de distinguer les appelants de votre API, mais que vous souhaitez ajouter des restrictions de clé API, vous pouvez créer une clé API distincte pour chaque appelant du même projet.

Pour créer une clé API pour chaque appelant dans le même projet :

1. Soit dans le projet dans lequel votre API est configurée, soit dans un projet dans lequel votre API est activée, créez pour chaque client une clé API disposant des restrictions de clés API dont vous avez besoin.
2. Donnez la clé API à chaque appelant.

Créer une clé API pour tous les appelants

Lorsque vous n'avez pas besoin de distinguer les appelants de votre API ni d'ajouter de restrictions d'API, mais que vous souhaitez quand même qu'une clé API soit exigée (pour empêcher l'accès anonyme, par exemple), vous pouvez créer une clé API que tous les appelants peuvent utiliser.

Pour créer une clé API pour tous les appelants :

1. Soit dans le projet dans lequel votre API est configurée, soit dans un projet dans lequel votre API est activée, créez une clé API pour tous les appelants disposant des restrictions de clés API dont vous avez besoin.
2. Donnez la même clé API à chaque appelant.

Restrictions liées aux applications

Les restrictions liées aux applications spécifient les sites Web, adresses IP ou applications qui peuvent utiliser votre clé API. Pour en savoir plus, consultez la section Ajouter des restrictions d’application.

Remarque : Si vous utilisez des référents HTTP (sites Web) comme restriction d'application, vous devez inclure un schéma (par exemple, https://) lorsque vous ajoutez la restriction de site Web. Par exemple, https://example.com/* est une restriction valide, mais example.com/* ne l'est pas.

Bonnes pratiques

Si vous utilisez des clés API pour protéger l'accès à votre API et à vos données utilisateur, veillez à définir l'option --service_control_network_fail_policy sur close lors de la configuration des options de démarrage d'Extensible Service Proxy v2 (ESPv2). La valeur par défaut de l'option est open.

ESPv2 appelle Service Control pour vérifier les clés API. Si des échecs réseau se produisent lors de la connexion à Service Control et qu'ESPv2 ne peut pas valider la clé API, cela entraîne le rejet de toutes les requêtes potentielles adressées à votre API avec des clés frauduleuses.

Étape suivante

• Quand et pourquoi utiliser les clés API
• Sécuriser une clé API