Ajouter des restrictions aux clés API

Les clés API identifient votre application ou votre site Web auprès de Google Cloud. Les restrictions de clé API garantissent que seules vos applications et vos sites Web peuvent utiliser vos clés. Pour des raisons de sécurité, nous vous recommandons d'ajouter des restrictions qui spécifient :

Quels clients ou sites Web peuvent utiliser vos clés API ?
Les API Google Cloud que votre application peut appeler à l'aide de vos clés API.

Si un client utilise une clé API restreinte pour émettre une requête qui ne respecte pas les restrictions de la clé API, la requête échoue. Par exemple, si une clé API exige que les requêtes HTTP soient émises à partir d'un domaine spécifique, mais qu'une requête HTTP est reçue à partir d'un autre domaine, la requête sera rejetée et une erreur sera générée.

Vous pouvez ajouter des restrictions lorsque vous créez une clé API avec la méthode CreateKey, ou vous pouvez les ajouter après la création de la clé à l'aide de la méthode UpdateKey. Cette page décrit les restrictions que vous pouvez ajouter à une clé API et vous explique comment les ajouter.

Avant de commencer

La page utilise curl et la Google Cloud CLI pour envoyer des requêtes à l'API API Keys. Pour savoir comment configurer l'API et l'expérimenter, consultez Premiers pas avec l'API API Keys.

Ajouter des restrictions de client

Les restrictions client spécifient les sites Web, adresses IP ou applications qui peuvent utiliser une clé API. Vous ajoutez des restrictions de client en fonction du type de client qui appelle votre API. Vous pouvez spécifier l'un des types de restrictions client suivants :

browserKeyRestrictions : URL de provenance HTTP (sites Web) autorisées à utiliser la clé.
serverKeyRestrictions : adresses IP des appelants autorisés à utiliser la clé.
androidKeyRestrictions : applications Android autorisées à utiliser la clé.
iosKeyRestrictions : applications iOS autorisées à utiliser la clé.

Ajouter des restrictions de navigateur

L'exemple suivant montre comment appeler la méthode UpdateKey pour limiter le référent HTTP à www.example.com :

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \
  --request PATCH \
  --data '{
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": "www.example.com"
      }
    },
    "etag": "ETAG"
  }'

Lorsque la réponse de operations.get contient "done": true, response contient le Key mis à jour avec les restrictions.

L'exemple suivant montre comment créer une clé API qui n'autorise que les requêtes HTTP provenant d'une liste d'URL spécifiques.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \
  --request POST \
  --data '{
    "displayName" : "API key with browser restrictions",
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": ["www.example.com", "www.example-2.com"]
      }
    }
  }'

Le tableau suivant présente quelques exemples de scénarios, et décrit les restrictions correspondantes appliquées dans le navigateur :

Scénario	Restrictions
Autoriser n'importe quelle URL de votre site	Vous devez définir deux URL dans la liste `allowedReferers`. URL du domaine, sans sous-domaine et avec un caractère générique représentant le chemin d'accès. Par exemple : `example.com/` Une deuxième URL comprenant un caractère générique pour le sous-domaine et un caractère générique pour le chemin d'accès. Par exemple : `.example.com/*`
Autoriser une URL spécifique	Vous devez ajoutez une URL avec un chemin d'accès exact. Par exemple : `www.example.com/path` `www.example.com/path/path`
Autoriser n'importe quelle URL dans un seul sous-domaine ou domaine nu	Vous devez définir deux URL dans la liste "allowedReferers" pour autoriser l'ensemble d'un domaine. URL du domaine, sans barre oblique finale. Exemple : `www.example.com` `sub.example.com` `example.com` Une deuxième URL pour le domaine, qui inclut un caractère générique pour le chemin d'accès. Exemple : `www.example.com/` `sub.example.com/` `example.com/*`

Ajouter des restrictions de serveur

Vous pouvez spécifier une ou plusieurs adresses IP pour les appelants, tels que des serveurs Web ou des jobs Cron, qui sont autorisés à utiliser votre clé API. Vous pouvez spécifier les adresses IP dans l'un des formats suivants :

IPv4 (198.51.100.1)
IPv6 (2001:db8::1)
Un sous-réseau utilisant la notation CIDR (198.51.100.0/24, 2001:db8::/64)

L'exemple suivant montre comment créer une clé API avec une liste de allowedIps :

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with server restrictions with IPv4, IPv6 and CIDR",
    "restrictions" : {
      "serverKeyRestrictions": {
        "allowedIps": ["198.51.100.1","198.51.100.0/24","2001:db8::1","2001:db8::/64"]
      }
    }
  }'

Ajouter des restrictions Android

Vous pouvez limiter l'utilisation d'une clé API à vos applications Android uniquement. Lorsque vous créez ou mettez à jour une clé API, indiquez le nom du package et l'empreinte SHA-1 de 20 octets pour chaque application.

Par exemple, supposons que vous ayez exécuté l'utilitaire keytool et qu'il ait créé l'empreinte digitale suivante :

  Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

L'exemple suivant montre comment créer une clé API avec l'empreinte digitale et le nom du package dans androidKeyRestrictions :

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with Android restrictions",
    "restrictions" : {
      "androidKeyRestrictions": {
        "allowedApplications": [
          {
            "sha1Fingerprint": "DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09",
            "packageName": "com.example.my.app"
          }
        ]
      }
    }
  }'

Ajouter des restrictions iOS

Vous pouvez restreindre l'utilisation d'une clé API à vos applications iOS uniquement en fournissant l'ID du bundle de chaque application lorsque vous créez ou mettez à jour une clé. L'exemple suivant montre comment définir iosKeyRestrictions lors de la création d'une clé API :

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with iOS restrictions",
    "restrictions" : {
      "iosKeyRestrictions": {
        "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"]
      }
    }
  }'

Ajouter des restrictions d'API

Les restrictions relatives aux API vous permettent de spécifier les API Google Cloud qui peuvent être appelées à l'aide de la clé API. Nous vous recommandons d'ajouter des restrictions au niveau du client et de l'API à toutes vos clés API.

Vous pouvez spécifier un ou plusieurs services dans les restrictions d'API. L'exemple suivant montre comment restreindre l'utilisation d'une nouvelle clé API aux seuls services translate.googleapis.com et datastore.googleapis.com :

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
  }'

Pour obtenir la liste des services activés dans votre projetGoogle Cloud , utilisez la commande gcloud services list.

En plus de restreindre l'utilisation de la clé API à des services spécifiques, vous pouvez éventuellement spécifier les méthodes de chaque service pour restreindre davantage la clé API. L'exemple suivant montre comment limiter la clé précédente aux méthodes autorisées de translate.googleapis.com :

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions  \
  --request PATCH \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
          "methods": [
            "Get*",
            "DetectLanguage"
          ]
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
    "etag": "ETAG"
  }'