Cette page a été traduite par l'API Cloud Translation.

Guide de démarrage rapide : Sécuriser le trafic vers un service avec la gcloud CLI

Cette page vous explique comment déployer une API sur API Gateway pour sécuriser le trafic vers un service de backend.

Suivez les étapes ci-dessous pour déployer une API permettant d'accéder à un service de backend sur Cloud Run Functions à l'aide de la Google Cloud CLI. Ce guide de démarrage rapide explique également comment utiliser une clé API pour protéger votre backend contre les accès non autorisés.

Avant de commencer

Dans la console Google Cloud , accédez à la page Tableau de bord, puis sélectionnez ou créez un projet Google Cloud .
Accéder à Google Dashboard

Remarque : Si vous ne prévoyez pas de conserver les ressources créées au cours de cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.
Vérifiez que la facturation est activée sur votre projet.
Activer la facturation
Vérifiez que la Google Cloud CLI est téléchargée et installée sur votre ordinateur.
Télécharger gcloud CLI
Mettez à jour les composants gcloud :
```
gcloud components update
```
Définissez le projet par défaut. Remplacez PROJECT_ID par l'ID du projet Google Cloud .
```
gcloud config set project PROJECT_ID
```

Activer les services requis

API Gateway nécessite l'activation des services Google suivants :

Nom	Titre
`apigateway.googleapis.com`	API de la passerelle API
`servicemanagement.googleapis.com`	API Service Management
`servicecontrol.googleapis.com`	API Service Control

Utilisez les commandes suivantes pour activer ces services :

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Pour en savoir plus sur les services gcloud, consultez la section Services gcloud.

Déployer un backend d'API

API Gateway se situe devant un service de backend déployé et gère toutes les requêtes entrantes. Dans ce guide de démarrage rapide, API Gateway achemine les appels entrants vers un backend Cloud Run Functions nommé helloGET, qui contient la fonction suivante :

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Suivez les étapes du Guide de démarrage rapide : utiliser Google Cloud CLI pour télécharger l'exemple de code Cloud Run Functions et déployer le service de backend de la fonction Cloud Run.

Créer une API

Vous êtes maintenant prêt à créer votre API sur API Gateway.

Saisissez la commande suivante, où :
- API_ID spécifie le nom de votre API. Consultez les exigences concernant les ID d'API pour connaître les consignes de dénomination des API.
```
gcloud api-gateway apis create API_ID 
```
Exemple :
```
gcloud api-gateway apis create my-api
```

Si l'opération réussit, vous pouvez utiliser la commande suivante pour afficher les détails de la nouvelle API :

gcloud api-gateway apis describe API_ID

Exemple :

gcloud api-gateway apis describe my-api

Cette commande renvoie les éléments suivants :

  createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

Notez la valeur de la propriété managedService. Cette valeur est utilisée pour activer votre API lors d'une étape ultérieure.

Créer une configuration d'API

Pour que API Gateway puisse être utilisé afin de gérer le trafic vers votre backend API déployé, il a besoin d'une configuration d'API.

Vous pouvez créer une configuration d'API à l'aide d'une description OpenAPI contenant des annotations spécialisées pour définir le comportement choisi d'API Gateway. Pour en savoir plus sur les extensions OpenAPI compatibles, consultez les pages suivantes :

La description OpenAPI utilisée pour ce guide de démarrage rapide contient des instructions de routage vers notre backend de fonction Cloud Run :

OpenAPI 2.0

# openapi-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://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

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
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

Pour importer cette description OpenAPI et créer une configuration d'API à l'aide de gcloud CLI :

Sur la ligne de commande, créez un fichier nommé openapi-functions.yaml.
Copiez et collez le contenu de la description OpenAPI dans le fichier que vous venez de créer.
Modifiez le fichier comme suit :
1. Dans le champ title, remplacez API_ID par le nom de votre API et optional-string par une brève description de votre choix. La valeur de ce champ est utilisée lors de la création de clés API qui accordent l'accès à cette API.
2. Dans le champ address, remplacez GATEWAY_LOCATION par la région Google Cloud de la fonction déployée et PROJECT_ID par le nom de votre projet Google Cloud .
Saisissez la commande suivante, où :
- CONFIG_ID spécifie le nom de votre configuration d'API.
- API_ID spécifie le nom de votre API.
- API_DEFINITION spécifie le nom du fichier de la spécification OpenAPI.
- SERVICE_ACCOUNT_EMAIL spécifie le compte de service utilisé pour signer les jetons pour les backends avec authentification configurée. Pour en savoir plus, consultez Configurer un compte de service.
  Remarque : Le compte de service utilisé pour créer une configuration d'API pour un backend Cloud Run Functions doit disposer du rôle cloudfunctions.invoker.
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
   --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Exemple :
```
gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
```
Cette opération peut prendre plusieurs minutes, car la configuration de l'API est propagée aux systèmes en aval. La création d'une configuration d'API complexe peut prendre jusqu'à dix minutes.

Remarque : Si vous exécutez cette commande et que vous recevez une erreur au format FAILED_PRECONDITION: Service Account ... does not exist, consultez Configurer un compte de service pour vérifier qu'un compte de service est activé pour votre projet.
Remarque : Vous ne pouvez créer qu'une seule configuration d'API à la fois pour une API donnée. Attendez la fin de la création de la configuration avant de tenter d'en créer une autre pour la même API.

Une fois la configuration de l'API créée, vous pouvez en afficher les détails en exécutant la commande suivante :

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

Exemple :

gcloud api-gateway api-configs describe my-config \
  --api=my-api

Le résultat affiche les détails de configuration de votre API, y compris le nom et l'état, comme illustré dans l'exemple suivant :

createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

Créer une passerelle

Déployez maintenant la configuration de l'API sur une passerelle. Le déploiement d'une configuration d'API sur une passerelle définit une URL externe permettant aux clients API d'accéder à votre API.

Exécutez la commande suivante pour déployer la configuration d'API que vous venez de créer sur API Gateway :

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION

où :

GATEWAY_ID spécifie le nom de la passerelle.
API_ID spécifie le nom de l'API API Gateway associée à cette passerelle.
CONFIG_ID spécifie le nom de la configuration d'API déployée sur la passerelle.
GCP_REGION est la Google Cloud région de la passerelle déployée.
Remarque :
Les valeurs autorisées sont les suivantes :
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
PROJECT_ID est le nom de votre projet Google Cloud .

Exemple :

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1

Si l'opération réussit, utilisez la commande suivante pour afficher les détails de la passerelle :

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION

Exemple :

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1

Cette commande renvoie les éléments suivants :

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

Notez la valeur de la propriété defaultHostname. Il s'agit de la partie nom d'hôte de l'URL de la passerelle que vous utiliserez pour tester votre déploiement à l'étape suivante.

Tester le déploiement de l'API

Vous pouvez maintenant envoyer des requêtes à votre API à l'aide de l'URL générée lors du déploiement de votre passerelle.

Saisissez la commande curl suivante, où :

DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de la passerelle déployée.
hello correspond au chemin d'accès spécifié dans la configuration de votre API.

curl https://DEFAULT_HOSTNAME/hello

Exemple :

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Le résultat est :

Hello World!

Vous avez réussi à créer et à déployer une passerelle API.

Sécuriser l'accès à l'aide d'une clé API

Pour sécuriser l'accès à votre backend d'API, générez une clé API associée à votre projet et accordez-lui l'accès nécessaire pour appeler votre API. Pour en savoir plus, consultez Restreindre l'accès à une API à l'aide de clés API.

Si vous n'avez pas encore de clé API associée au projet Google Cloud que vous utilisez dans ce guide de démarrage rapide, vous pouvez en ajouter une en suivant les étapes décrites dans Créer une clé API.

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

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

Modifiez la description 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 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://GATEWAY_LOCATION-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.

Créez une configuration d'API avec la spécification 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 \
--backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Par exemple :

gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com

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

Par exemple:

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

Tester votre clé API

Une fois que vous avez créé et déployé l'API modifiée, envoyez-lui une requête.

Saisissez la commande curl suivante, où :

DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de la passerelle déployée.
hello correspond au chemin d'accès spécifié dans la configuration de votre API.

curl https://DEFAULT_HOSTNAME/hello

Exemple :

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

L'erreur suivante devrait se produire :

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

Saisissez la commande curl suivante, où :

DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de la passerelle déployée.
hello correspond au chemin d'accès spécifié dans la configuration de votre API.
API_KEY spécifie la clé API que vous avez créée à l'étape précédente.

curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

Hello World! devrait maintenant s'afficher dans la réponse de votre API.

Félicitations ! Vous avez réussi à protéger votre backend d'API avec une passerelle API. Vous pouvez maintenant commencer à intégrer de nouveaux clients API en générant d'autres clés API.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce guide de démarrage rapide ne soient facturées sur votre compte Google Cloud , vous pouvez :

Vous pouvez également supprimer le projet Google Cloud utilisé pour ce tutoriel.

Étapes suivantes

En savoir plus sur API Gateway
Parcourez la section Configurer l'environnement de développement.
En savoir plus sur l'authentification entre différents services