Utiliser des clés API

Cette page explique comment utiliser les clés API dans API Gateway.

Une clé API est une chaîne qui identifie un projetGoogle Cloud à des fins de gestion des quotas, de facturation et de surveillance. Les développeurs génèrent une clé API dans un projet de la console Google Cloud . Ils intègrent ensuite cette clé à chaque appel de votre API en tant que paramètre de requête ou dans un en-tête de requête.

Si vous spécifiez une exigence de clé API dans la configuration de votre API, API Gateway utilise la clé API pour rechercher le projet Google Cloud associé. API Gateway n'accepte que les requêtes comportant une clé API générée dans votre projet Google Cloud ou dans l'un des autres projetsGoogle Cloud au sein desquels votre API a été activée.

Remarque : Contrairement aux identifiants basés sur des jetons à court terme ou sur des requêtes signées, les clés API sont incluses dans la requête API. Par conséquent, les clés API sont vulnérables aux attaques de l'homme du milieu et sont moins sécurisées que les autres identifiants d'authentification. Vous pouvez utiliser des clés API en plus de l'une des autres formes d'authentification compatibles, mais nous vous déconseillons d'utiliser uniquement des clés API lorsque les appels d'API contiennent des données sensibles.

Pour créer une clé API ou afficher celles déjà disponibles dans votre projet Google Cloud , accédez à la page API et services > Identifiants.

Accéder à "Identifiants"

Utiliser une clé API

Pour utiliser des fonctionnalités API Gateway, telles que les quotas, vous pouvez transmettre une clé API permettant à API Gateway d'identifier le Google Cloud projet auquel l'application cliente est associée.

Configurer l'authentification par clé API pour API Gateway

Pour sécuriser l'accès à votre passerelle à l'aide d'une clé API :

1. Activez la prise en charge des clés API pour votre service. Saisissez la commande suivante, où :
   • MANAGED_SERVICE_NAME spécifie le nom du service géré créé lorsque vous avez déployé l'API. Vous pouvez l'afficher dans la propriété "Managed Service" (Service géré) listée avec la commande gcloud api-gateway apis describe.
   • PROJECT_ID est le nom de votre projet Google Cloud .

   gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

   Par exemple:

   gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog

2. Modifiez la spécification OpenAPI utilisée pour créer la configuration de votre API afin d'inclure des instructions permettant d'appliquer une stratégie de sécurité pour la validation des clés API à tout le trafic. Ajoutez le type security et securityDefinitions ou securitySchemes comme indiqué ci-dessous :

   OpenAPI 2.0

     # openapi2-functions.yaml
     swagger: '2.0'
     info:
       title: API_ID optional-string
       description: Sample API on API Gateway with a Google Cloud Functions backend
       version: 1.0.0
     schemes:
       - https
     produces:
       - application/json
     paths:
       /hello:
         get:
           summary: Greet a user
           operationId: hello
           x-google-backend:
             address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
           security:
           - api_key: []
           responses:
             '200':
               description: A successful response
               schema:
                 type: string
     securityDefinitions:
       # This section configures basic authentication with an API key.
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   securityDefinition configure votre API pour qu'elle exige une clé API transmise en tant que paramètre de requête nommé key lors de la demande d'accès à tous les chemins définis dans la spécification.

   OpenAPI 3.x

   # openapi-functions.yaml
   openapi: 3.0.4
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with a Google Cloud Functions backend
     version: 1.0.0
   # Define reusable components in x-google-api-management
   x-google-api-management:
     backend:
       functions_backend:
         address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
         pathTranslation: APPEND_PATH_TO_ADDRESS
         protocol: "http/1.1"
   # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
   x-google-backend: functions_backend
   components:
   # This section configures basic authentication with an API key.
     securitySchemes:
       google_api_key:
         type: apiKey
         name: x-api-key
         in: header
   security:
     - google_api_key: []
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           '200':
             description: A successful response
             content:
               application/json:
                 schema:
                   type: string

   securitySchemes configure votre API pour qu'elle exige une clé API transmise en tant que paramètre de requête nommé key lors de la demande d'accès à tous les chemins définis dans la spécification.

3. Créez une configuration d'API avec la description OpenAPI modifiée à l'aide de la commande suivante :

   gcloud api-gateway api-configs create NEW_CONFIG_ID \
   --api=API_ID --openapi-spec=NEW_API_DEFINITION \
   --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   Par exemple :

   gcloud api-gateway api-configs create my-config-key \
     --api=my-api --openapi-spec=openapi-functions.yaml \
     --project=my-project --backend-auth-service-account=[e-mail]

4. Exécutez la commande suivante pour mettre à jour votre passerelle existante avec la nouvelle configuration d'API :

   gcloud api-gateway gateways update GATEWAY_ID \
     --api=API_ID --api-config=NEW_CONFIG_ID \
     --location=GATEWAY_LOCATION --project=PROJECT_ID

   Par exemple:

   gcloud api-gateway gateways update my-gateway \
     --api=my-api --api-config=my-config-key \
     --location=us-central1 --project=my-project

Restreindre les clés API

Par défaut, les clés API ne sont pas restreintes, ce qui les rend vulnérables à une utilisation non autorisée. Ajoutez des restrictions d'API chaque fois que possible. Les restrictions relatives aux API définissent les API qui peuvent être appelées à l'aide de la clé API. Toutes les clés API utilisées dans des applications de production doivent employer des restrictions d'API.

Pour ajouter des restrictions d'API :

1. Recherchez le titre de l'API indiqué dans la configuration de votre API. Dans l'exemple suivant, le titre de l'API est My Example Config :

   OpenAPI 2.0

   # openapi.yaml
   swagger: '2.0'
   info:
     title: My Example Config
     description: Sample API on API Gateway
     version: 1.0.0
   ...

   OpenAPI 3.x

   # openapi.yaml
   openapi: 3.0.4
   info:
     title: My Example Config
     description: Sample API on API Gateway
     version: 1.0.0
   ...

2. Dans la console Google Cloud , accédez à la page API et services > Identifiants.

   Accéder à "Identifiants"

3. Sélectionnez le nom de la clé API que vous souhaitez utiliser pour votre API.

4. Dans la section Restrictions relatives aux API de la page d'informations sur la clé API, cliquez sur Restreindre la clé.

5. Dans la liste déroulante des API disponibles, sélectionnez celle à laquelle votre clé API permettra d'accéder. Par exemple, sélectionnez My Example Config.

6. Cliquez sur Enregistrer.

Votre restriction devrait prendre effet dans un instant.