Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Gestion et sécurité des clés API

1. Introduction

Historiquement, les clés API Google étaient utilisées pour accéder aux API Google lorsque d'autres méthodes n'étaient pas disponibles ou étaient considérées comme peu pratiques. Les cas d'utilisation courants étaient l'accès à l'API Google Maps et aux API Google exposées par Firebase. Avec l'introduction des modèles d'IA, des agents d'IA comme Gemini, d'AI Studio et des frameworks de développement d'agents comme Agent Development Kit, les clés API sont devenues une méthode principale d'accès aux grands modèles de langage de Google.

Les clés API offrent un faible niveau de protection. Bien que Google Cloud propose plusieurs méthodes pour éviter une utilisation abusive des clés, posséder une clé API active permet d'accéder aux API Google sans aucune validation d'authentification ou d'autorisation supplémentaire. Les méthodes de restriction de l'utilisation des clés API sont décrites dans la documentation. L'article Sécuriser vos clés API Gemini et Google sur le blog Cloud fournit des recommandations supplémentaires sur la maintenance des clés API. Dans cet atelier de programmation, vous mettrez ces recommandations en pratique.

Objectifs de l'atelier

Examiner les restrictions appliquées lors de la création de clés API dans Google Cloud
Cataloguer toutes vos clés API et trouver celles qui ne sont pas protégées
Appliquer des restrictions aux clés API existantes en fonction de leur utilisation
Définir une automatisation qui supprime la clé en cas d'utilisation anormale

Ce dont vous avez besoin

Un navigateur Web moderne (tel que Chrome).
Un compte Google

2. Configuration

Les instructions de cet atelier de programmation supposent que vous exécutez des commandes dans Cloud Shell dans la console Google Cloud. Si vous disposez de gcloud CLI dans votre environnement local, vous pouvez y exécuter les commandes.

Bien que les opérations décrites dans les étapes puissent être effectuées à l'aide de l'interface utilisateur de la console Cloud, les méthodes sont différentes. Cet atelier de programmation utilise l'interface de ligne de commande pour simplifier les interactions et faciliter l'intégration avec les agents d'IA modernes (comme Antigravity CLI).

Démarrer un terminal Cloud Shell

Ouvrez la console Google Cloud à l'aide de l'URL https://console.cloud.google.com/ dans une nouvelle fenêtre de navigateur. Pour une expérience utilisateur optimale, nous vous recommandons d'utiliser Chrome.
Connectez-vous à votre compte Google dans Google Cloud.
Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
Si cette option s'affiche, passez les fenêtres suivantes :
- Accédez à la fenêtre d'informations de Cloud Shell.
- Autorisez Cloud Shell à utiliser vos identifiants pour effectuer des appels d'API Google Cloud.

Sélectionner un projet Google Cloud

Une fois que vous avez ouvert Cloud Console, vous êtes authentifié et une sélection de projet est généralement disponible pour votre travail. L'ID du projet est une séquence de 6 à 30 caractères composée de lettres minuscules, de chiffres et de traits d'union, par exemple qwiklabs-gcp-04-3075fc9fd77f. Le terminal Cloud Shell configure gcloud CLI avec le projet sélectionné. Un résultat semblable aux lignes suivantes s'affiche :

Your Cloud Platform project in this session is set to qwiklabs-gcp-04-3075fc9fd77f

Cela signifie que vos commandes ultérieures à gcloud utiliseront l'ID du projet qwiklabs-gcp-04-3075fc9fd77f.

Définissez l'ID du projet en tant que variable d'environnement PROJECT_ID. Vous pouvez afficher la liste de tous vos projets à l'aide de la commande suivante :

gcloud projects list

Remplacez your-project-id et exécutez la commande si vous souhaitez utiliser un ID de projet différent de celui configuré dans gcloud.
```
export PROJECT_ID="your-project-id"
```
Par exemple :
```
export PROJECT_ID="qwiklabs-gcp-04-3075fc9fd77f"
```
Exécutez la commande suivante si vous souhaitez utiliser l'ID du projet sélectionné :
```
export PROJECT_ID=$(gcloud config get project)
```

3. Restreindre une nouvelle clé API

Auparavant, les utilisateurs pouvaient créer des clés API totalement illimitées. Les clés illimitées pouvaient être utilisées pour appeler N'IMPORTE QUELLE API Google activée dans le projet où la clé avait été créée. Bien que la console Google Cloud empêche les utilisateurs de créer des clés illimitées, il est toujours possible de le faire à l'aide de gcloud CLI ou d'appels d'API directs.

Les étapes suivantes montrent comment créer une clé API limitée qui restreint l'utilisation à l'API spécifique et au site Web spécifié.

Pour créer une clé API limitée à l'utilisation de l'API de géolocalisation Google Maps, exécutez la commande suivante dans le terminal shell :
```
gcloud services api-keys create --key-id=restricted-api-key \
  --display-name="restricted api key" \
  --api-target=service=geolocation.googleapis.com \
  --project=${PROJECT_ID}
```
Cette commande crée une clé API qui ne peut être utilisée QUE pour appeler le service de géolocalisation Google Maps.
ℹ️ Remarque : Il est possible d'ajouter plusieurs API à la liste limitée. Utilisez plusieurs paramètres --api-target avec une valeur =service=SERVICE.googleapis.com, où SERVICE est l'un des services Google.
Renforcez la sécurité de la clé en ajoutant une restriction d'application. Limitez l'utilisation de la clé à tous les chemins du site Web example.com uniquement. Exécutez la commande suivante pour ajouter la restriction d'application à la clé :
```
gcloud services api-keys update restricted-api-key \
  --location=global \
  --allowed-referrers="example.com/*" \
  --project=${PROJECT_ID}
```
Au lieu d'autoriser l'utilisation de la clé sur un ou plusieurs sites Web spécifiques, vous pouvez utiliser --allowed-application pour définir l'application Android autorisée ouallowed-ips pour définir les adresses IP autorisées. Consultez la documentation complète pour connaître toutes les options.
ℹ️ Remarque : Il est possible d'ajouter plusieurs restrictions d'application du MÊME type en fournissant plusieurs paramètres (par exemple, --allowed-referrers). Si vous ajoutez plusieurs types de restrictions d'application, seul le dernier type sera enregistré dans la liste des paramètres.

Libérer de l'espace

Supprimez la clé API que vous avez créée, sauf si vous prévoyez de l'utiliser :

gcloud services api-keys delete --key-id=restricted-api-key \
  --project=${PROJECT_ID}

4. Cataloguer vos clés API

Au cours de cette étape, vous allez utiliser gcloud CLI pour obtenir un inventaire de vos clés API. La liste obtenue affiche toutes les clés API actives (non supprimées) auxquelles vous avez accès.

Exécutez la commande suivante pour afficher tous les noms de clés, les ID et les dates de création :
```
gcloud services api-keys list --project=${PROJECT_ID} \
  --format='value(displayName,name.basename(),createTime.date())'
```
Le résultat affiche le nom lisible de la clé, l'ID de la clé et la date de création de la clé. Il ressemble à ce qui suit :
```
api key 1	api-key-1	2024-05-10T07:53:24
api key 2	api-key-2	2025-06-12T14:47:57
```
Sélectionnez l'un des ID de clé et collez la commande suivante pour vérifier si la clé comporte des restrictions. Remplacez your-key-id par la valeur de l'ID de clé sélectionné :
```
gcloud services api-keys describe "your-key-id" --project=${PROJECT_ID}
```

Le résultat (au format YAML) contient une liste de restrictions sous restrictions.

createTime: '2024-05-10T07:53:24.986528Z'
displayName: api key 1
etag: W/"u1WuY41K2tPKUZd7cfLoKg=="
name: projects/123456789012/locations/global/keys/api-key-1
restrictions:
  apiTargets:
  - service: geolocation.googleapis.com
  browserKeyRestrictions:
    allowedReferrers:
    - https://example.com/*
uid: 1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6
updateTime: '2024-05-10T07:53:24.071228Z'

Notez que si la clé n'a jamais été mise à jour, les champs createTime et updateTime auront le même code temporel.

Téléchargez et exécutez le script qui parcourt tous vos projets et affiche toutes les clés API SANS RESTRICTION :

curl -fsSL -o unrestricted_api_keys.sh \
  "https://github.com/GoogleCloudPlatform/devrel-demos/blob/main/security/api-key-audit/unrestricted_api_keys.sh"
chmod +x unrestricted_api_keys.sh
./unrestricted_api_keys.sh

Une fois le script exécuté, un résultat s'affiche au format suivant :

DISPLAY NAME    KEY ID    PROJECT ID    CREATION DATE
Key 1    1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6    my-project-1    2024-05-10T07:53:24.071228Z

Vous trouverez tous les scripts utilisés dans cet atelier de programmation dans le dossier Security du dépôt devrel-demos sur GitHub.

5. Découvrir l'utilisation d'une clé API

Au cours de cette étape, vous allez interroger les métriques Google Cloud qui vous aideront à déterminer les API qui ont été appelées à l'aide de votre clé API. Grâce à ces informations, vous pouvez examiner l'utilisation actuelle des clés et appliquer des restrictions d'API à la clé en fonction d'informations réelles au lieu de faire une estimation.

Utilisez le même ID de clé que celui utilisé à l'étape précédente ou sélectionnez un autre ID de clé. Remplacez your-key-id par l'ID de clé choisi dans la commande suivante :
```
export KEY_UID=$(
   gcloud services api-keys describe "your-key-id" \
   --format='value(uid)' \
   --project=${PROJECT_ID})
```
Définissez la recherche pour examiner l'historique d'utilisation sur un an. Si vous souhaitez rechercher une période plus longue ou plus courte, remplacez 365 (nombre de jours) par un autre nombre positif.
```
export DAYS=365
```
Actualisez les identifiants par défaut de l'application (ADC) pour activer l'appel direct à l'API Cloud Monitoring. Exécutez la commande suivante et suivez les instructions du terminal :
```
gcloud auth application-default login
```
Exécutez la commande suivante pour envoyer une requête de données de métriques d'utilisation du service à l'API Cloud Monitoring :

curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  --data-urlencode "filter=metric.type=\"serviceruntime.googleapis.com/api/request_count\" AND resource.labels.credential_id=\"apikey:${KEY_UID}\"" \
  --data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)" \
  --data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  "https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries" \
  | jq -r '.timeSeries[]?.resource.labels.service' | sort -u

La commande interroge la métrique intégrée serviceruntime/api/request_count pour les points de données avec le libellé credential_id qui correspondent à l'ID unique de la clé API choisie. Elle récupère ensuite les valeurs du libellé service et les affiche en éliminant les doublons.

Renforcer la sécurité des clés API

Au cours de cette étape, vous allez utiliser les informations collectées lors des étapes précédentes pour mettre à jour la configuration des restrictions de la clé API en fonction des informations d'utilisation.

Vous utiliserez la même clé API que celle utilisée à l'étape précédente. Si nécessaire, réexécutez les instructions des étapes précédentes pour vous assurer que les variables d'environnement PROJECT_ID, KEY_UID et DAYS sont définies.

Exécutez la commande suivante pour récupérer la liste des API Google appelées à l'aide de la clé API :

SERVICES=$(curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
–data-urlencode "filter=metric.type="serviceruntime.googleapis.com/api/request_count" AND resource.labels.credential_id="apikey:${KEY_UID}""
–data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)"
–data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
"https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries"
| jq -r ‘.timeSeries[]?.resource.labels.service' | sort -u)

1. Build the list of arguments to restrict the API usage for the API key based
on the retrieved list.

```shell
API_TARGET_ARGS=()
for SERVICE in $SERVICES; do
  API_TARGET_ARGS+=("--api-target=service=${SERVICE}")
done

Remplacez la liste des API limitées par la liste non vide :

if [ ${#API_TARGET_ARGS[@]} -gt 0 ]; then
    gcloud services api-keys update "projects/${PROJECT_ID}/locations/global/keys/${KEY_UID}" \
    ${API_TARGET_ARGS}
fi

6. Définir la détection d'utilisation anormale

Les étapes précédentes ont montré comment explorer et renforcer la sécurité des clés API. Cette étape explique comment automatiser une réponse à un pic inattendu d'utilisation de la clé à l'aide des alertes Monitoring.

Les instructions suivantes créent une alerte qui se déclenche lorsque le taux d'appels d'API utilisant une clé API augmente de plus de 10% au cours des cinq dernières minutes. L'alerte est configurée pour déclencher un script Cloud Build qui supprime la clé API afin d'empêcher toute utilisation ultérieure. La clé peut être restaurée au cours des 30 prochains jours. Consultez la documentation pour savoir comment annuler la suppression de la clé.

Les instructions réutilisent les variables PROJECT_ID et KEY_UID que vous avez utilisées lors des étapes précédentes. Si vous souhaitez sélectionner une autre clé et/ou un autre projet, définissez les nouvelles valeurs de ces variables comme décrit dans les étapes Configuration et Découvrir l'utilisation d'une clé API.

Exécutez le script suivant pour créer un fichier de règle d'alerte :

cat <<EOF > alert_policy.json
{
  "displayName": "Credential API Request Count Increase Alert (Project: ${PROJECT_ID})",
  "combiner": "OR",
  "conditions": [
    {
      "displayName": "API Request Count Increase > 10% in 5m with Min Volume",
      "conditionPrometheusQueryLanguage": {
        "query": "(sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) / (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m] offset 5m)) or on() vector(1)) > 1.10) and (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) > 50)",
        "duration": "0s",
        "evaluationInterval": "60s"
      }
    }
  ],
  "enabled": true
}
EOF

La règle d'alerte utilise le filtre PromQL suivant pour déclencher l'alerte :

 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m])
 ) /
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m] offset 5m)
 ) or on() vector(1)) > 1.10)
and
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\"YOUR_CREDENTIAL_ID_HERE\"}[5m])) > 50)

Il calcule le taux d'augmentation et le compare à une fenêtre précédente. L'alerte ne se déclenche que si le taux est supérieur de plus de 10 %. Pour éviter de déclencher l'alerte lorsque le nombre total d'appels est négligeable, il conditionne le déclenchement à plus de 50 appels d'API dans la fenêtre. Pour éviter le calcul NaN (suppression par zéro) lorsque le taux de la fenêtre de cinq minutes précédente était de 0, il remplace le dénominateur par 1 si le taux de la fenêtre précédente est nul.Vous pouvez modifier les paramètres d'alerte tels que la durée de la fenêtre (5m), le seuil minimal (50) ou le seuil d'augmentation de 10 % (1.10).Les paramètres de règle supplémentaires définissent qu'une fois la condition atteinte, l'alerte doit être déclenchée (duration) et que la condition doit être sondée toutes les 60 secondes (evaluationInterval).

Exécutez la commande suivante pour créer un sujet Pub/Sub qui sera utilisé pour publier des notifications d'alerte :
```
gcloud pubsub topics create api-key-alert-notifications --project=$PROJECT_ID
```

Exécutez la commande suivante pour créer des canaux de notification pour les alertes qui utilisent Pub/Sub.

CHANNEL_NAME=$(gcloud beta monitoring channels create \
  --display-name="Pub/Sub Alert Channel" \
  --type="pubsub" \
  --channel-labels="topic=projects/$PROJECT_ID/topics/api-key-alert-notifications" \
  --format='value(name)' \
  --project=$PROJECT_ID)

Vous utiliserez la variable d'environnement CHANNEL_NAME à l'étape Effectuer un nettoyage.

Exécutez la commande suivante pour créer une alerte Monitoring :

gcloud monitoring policies create --policy-from-file=alert_policy.json \
  --project=$PROJECT_ID

Exécutez la commande suivante pour accorder les autorisations du service Cloud Build afin de supprimer les clés API du projet.
```
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"
```
Il est possible de limiter le rôle apikeys.admin afin de ne manipuler que des instances spécifiques des clés API. Pour en savoir plus, consultez Conditions IAM.

Exécutez le script suivant pour créer un déclencheur de compilation Cloud Build qui supprime la clé API.

cat <<EOF > trigger_config.yaml
name: "delete-compromised-api-key"
description: "Triggered by Pub/Sub alert to automatically delete the leaking API Key"
pubsubConfig:
  topic: "projects/${PROJECT_ID}/topics/api-key-alert-notifications"
build:
  steps:
  - name: "gcr.io/google.com/cloudsdktool/cloud-sdk:slim"
    args:
    - "gcloud"
    - "services"
    - "api-keys"
    - "delete"
    - "${KEY_UID}"
    - "--quiet"
EOF

Exécutez la commande suivante pour créer un déclencheur d'alerte Monitoring :

gcloud builds triggers create pubsub \
  --trigger-config=trigger_config.yaml \
  --project=$PROJECT_ID

Vous pouvez maintenant supprimer les fichiers de configuration de la règle d'alerte et du déclencheur de compilation Cloud Build :

rm alert_policy.json trigger_config.yaml

Vous pouvez également configurer cette automatisation à l'aide du plan Terraform. Téléchargez les fichiers Terraform à partir du dossier abnormal-usage-detection dans le dépôt Google Cloud DevRel repository. Le plan accepte un ID de projet et un UID de clé API comme paramètres d'entrée, et configure les ressources et les configurations que vous avez vues lors de cette étape.

7. Libérer de l'espace

Pour éviter des frais inattendus sur votre compte Google Cloud, n'oubliez pas de supprimer le sujet Pub/Sub, le déclencheur de compilation Cloud Build et les règles d'alerte créés lors de cet exercice.

Exécutez les commandes suivantes pour supprimer toutes les ressources que vous avez créées :

gcloud builds triggers delete delete-compromised-api-key \
  --project=$PROJECT_ID
gcloud beta monitoring channels delete $CHANNEL_NAME \
  --project=$PROJECT_ID \
  --quiet
gcloud pubsub topics delete api-key-alert-notifications \
  --project=$PROJECT_ID
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"

8. Résumé

Dans cet atelier de programmation, vous avez implémenté un framework de sécurité et d'automatisation de bout en bout robuste pour les clés API Google Cloud :

Configurations par défaut renforcées : vous avez créé et limité des clés API pour restreindre l'accès exclusivement aux API nécessaires et aux plates-formes de confiance (telles que des référents HTTP spécifiques).
Audit de votre inventaire de clés : vous avez analysé vos environnements de projet pour détecter et isoler les clés illimitées qui présentent un risque de sécurité immédiat.
Analyse des données d'utilisation : vous avez interrogé par programmation les données de métriques Cloud Monitoring pour profiler l'utilisation historique des clés, ce qui vous a permis de limiter les clés en fonction des empreintes d'utilisation vérifiées.
Atténuation automatisée des menaces : vous avez établi un "disjoncteur" réactif en connectant une règle d'alerte Cloud Monitoring à un sujet Pub/Sub et à un déclencheur de compilation Cloud Build, ce qui vous permet de supprimer automatiquement les clés compromises lors de pics de trafic anormaux.

Étapes suivantes

Appliquer des restrictions à toutes vos clés API : utilisez ce que vous avez appris dans cet atelier pour détecter toutes les clés API partiellement limitées ou illimitées, et appliquez des restrictions d'API et de client.
Configurer un "disjoncteur" sur les clés API : protégez davantage vos clés API contre une utilisation inattendue en configurant la suppression automatique des clés en cas d'augmentation soudaine de la consommation. Utilisez les commandes gcloud ou Terraform présentées dans l'atelier. Envisagez de renforcer les autorisations à l'aide des conditions IAM.
Explorer les alertes Monitoring : découvrez comment configurer des alertes à l'aide du service Google Cloud Monitoring.
En savoir plus sur le contrôle des accès disponible dans Google Cloud : consultez les règles de limite d'accès et la propagation des modifications d'accès.