Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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 les plus 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, et des frameworks de développement AI Studio et Agent comme Agent Development Kit, les clés API sont devenues la principale méthode 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 l'utilisation abusive des clés, la possession d'une clé API active permet d'accéder aux API Google sans aucune validation supplémentaire de l'authentification ou de l'autorisation. Les méthodes permettant de restreindre l'utilisation des clés API sont décrites dans la documentation. L'article Sécuriser vos clés API Gemini et Google du blog Cloud fournit des recommandations supplémentaires sur la gestion des clés API. Dans cet atelier de programmation, vous allez mettre ces recommandations en pratique.

Objectifs de l'atelier

Examiner les restrictions appliquées lors de la création de clés API sur Google Cloud
Cataloguer toutes vos clés API et identifier 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

Prérequis

Un navigateur Web récent (tel que Chrome)
Un compte Google

2. Configuration

Les instructions de cet atelier de programmation supposent que vous exécutez les 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 aux agents d'IA modernes (comme Antigravity CLI).

Démarrer un terminal Cloud Shell

Ouvrez la console Google Cloud en accédant à 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 elles s'affichent, 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 la console Cloud ouverte, vous êtes authentifié et vous pouvez généralement sélectionner un projet pour votre travail. L'ID du projet est une séquence de 6 à 30 caractères (lettres minuscules, chiffres et tirets), par exemple qwiklabs-gcp-04-3075fc9fd77f. Le terminal Cloud Shell configure la CLI gcloud 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 prochaines commandes 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 sans aucune restriction. Les clés sans restriction peuvent être utilisées pour appeler N'IMPORTE QUELLE API Google activée dans le projet où la clé a été créée. Bien que la console Google Cloud empêche les utilisateurs de créer des clés sans restriction, il est toujours possible de le faire à l'aide de la CLI gcloud ou d'appels d'API directs.

Les étapes suivantes montrent comment créer une clé API restreinte qui limite l'utilisation à l'API spécifique et au site Web indiqué.

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 du 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 restreinte. Utilisez plusieurs paramètres --api-target avec la 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 d'accès 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é pour des sites Web spécifiques, vous pouvez utiliser --allowed-application pour définir les applications Android autorisées ouallowed-ips pour définir les adresses IP autorisées. Consultez la documentation complète pour découvrir 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 de la liste des paramètres sera enregistré.

Effectuer un nettoyage

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 la CLI gcloud pour obtenir un inventaire de vos clés API. La liste qui s'affiche contient toutes les clés API actives (non supprimées) auxquelles vous avez accès.

Exécutez la commande suivante pour afficher tous les noms et ID de clés, ainsi que les dates de création :
```
gcloud services api-keys list --project=${PROJECT_ID} \
  --format='value(displayName,name.basename(),createTime.date())'
```
Le résultat affichera le nom lisible de la clé, son ID et la date de sa création. Cela ressemblerait à quelque chose comme ceci :
```
api key 1	api-key-1	2024-05-10T07:53:24
api key 2	api-key-2	2025-06-12T14:47:57
```
Choisissez 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) contiendra 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 semblable à ce qui suit s'affiche :

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 de sécurité du dépôt devrel-demos sur GitHub.

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

Dans cette étape, vous allez interroger les métriques Google Cloud qui vous aideront à identifier les API 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 des informations réelles, au lieu de faire une supposition.

Utilisez le même ID de clé que celui utilisé à l'étape précédente ou choisissez-en un autre. 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 afficher l'historique d'utilisation sur un an. Si vous souhaitez rechercher des données sur une période plus ou moins longue, remplacez 365 (nombre de jours) par un autre nombre positif.
```
export DAYS=365
```
Actualisez les identifiants par défaut de l'application (ADC) pour permettre l'appel direct à l'API Cloud Monitoring. Exécutez la commande suivante et suivez les instructions dans le 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 dont le libellé credential_id correspond à l'ID unique de la clé API choisie. Il récupère ensuite les valeurs du libellé service et les affiche en éliminant les doublons.

Renforcer la clé API

Lors de cette étape, vous allez utiliser les informations recueillies 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 restreintes 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 des anomalies d'utilisation

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

Les instructions suivantes permettent de créer 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. Vous pouvez restaurer la clé 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 de configuration et de découverte de l'utilisation d'une clé API.

Exécutez le script suivant pour créer un fichier de règles 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. et ne déclenche l'alerte que si elle est supérieure de plus de 10 %. Pour éviter de déclencher l'alerte lorsque le nombre total d'appels est négligeable, elle conditionne le déclenchement à plus de 50 appels d'API dans la fenêtre. Pour éviter le calcul NaN (supprimer par zéro) lorsque le taux de 5 minutes précédent était de 0, le dénominateur est remplacé par 1 si le taux de la fenêtre précédente est de 0.Vous pouvez modifier les paramètres de l'alerte, tels que la durée de la fenêtre (5m), le seuil minimal (50) ou le seuil d'augmentation de 10 % (1.10).D'autres paramètres de règle définissent que, une fois la condition atteinte, l'alerte doit être déclenchée (duration) et que la condition doit être vérifié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 un canal 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 "Nettoyer".

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

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

Exécutez la commande suivante pour accorder au service Cloud Build l'autorisation 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 à la manipulation d'instances spécifiques de 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 d'un plan Terraform. Téléchargez les fichiers Terraform depuis le dossier abnormal-usage-detection du dépôt Google Cloud DevRel. 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. Effectuer un nettoyage

Pour éviter des frais inattendus sur votre compte Google Cloud, n'oubliez pas de supprimer la rubrique 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 d'automatisation et de sécurité 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 URL de provenance HTTP spécifiques).
Vous avez audité votre inventaire de clés : vous avez analysé les environnements de votre projet pour détecter et isoler les clés non restreintes qui présentent un risque de sécurité immédiat.
Données d'utilisation analysées : vous avez interrogé de manière programmatique les données de métriques Cloud Monitoring pour profiler l'utilisation historique des clés, ce qui vous a permis de restreindre les clés en fonction des empreintes d'utilisation validées.
Atténuation automatisée des menaces : vous avez établi un "disjoncteur" réactif en associant une règle d'alerte Cloud Monitoring à un sujet Pub/Sub et à un déclencheur de compilation Cloud Build. Cela vous permet de supprimer automatiquement les clés compromises lors de pics de trafic anormaux.

Étapes suivantes

Appliquez 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 restreintes ou non restreintes, puis 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 indiquées dans l'atelier. Envisagez de renforcer les autorisations à l'aide des conditions IAM.
Découvrez les alertes Monitoring : apprenez à 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 relatives aux limites d'accès et la propagation des modifications d'accès.