Ajouter des restrictions aux clés API

Les clés API identifient votre application ou votre site Web dans Google Cloud. Les restrictions relatives aux clés API garantissent que seuls vos applications et sites Web peuvent les utiliser. 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 satisfait pas aux restrictions de clé API, la requête échoue. Par exemple, si une clé API nécessite que les requêtes HTTP soient émises depuis un domaine spécifique, mais qu'une requête HTTP soit reçue depuis un autre domaine, la requête est rejetée avec une erreur.

Vous pouvez ajouter des restrictions lorsque vous créez une clé API avec la méthode CreateKey. Vous pouvez également 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 montre comment les ajouter.

Avant de commencer

La page utilisecurl avec la oauth2l pour envoyer des requêtes à l'API Keys API. Pour savoir comment configurer l'API, consultez la page Premiers pas avec les clés API.

Ajouter des restrictions côté client

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

browserKeyRestrictions: URL de provenance HTTP (sites Web) autorisées à utiliser la clé.
serverKeyRestrictions: adresses IP des appelants autorisés à utiliser la clé.
androidKeyRestrictions: les 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 restreindre l'URL de provenance 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, l'élément 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 à partir 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 montre quelques exemples de scénarios et de restrictions de navigateur:

Scénario	Restrictions
Autoriser n'importe quelle URL de votre site	Vous devez définir deux URL dans la liste "allowedReferrers". URL pour le domaine, sans sous-domaine, et avec un caractère générique pour 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	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 "allowedReferrers" afin d'autoriser un domaine entier. URL du domaine, sans barre oblique finale. Par exemple: `www.example.com` `sub.example.com` `example.com` Il s'agit de la seconde URL qui inclut un caractère générique pour le chemin d'accès. Par exemple: `www.example.com/` `sub.example.com/` `example.com/*`

Ajouter des restrictions de serveur

Vous pouvez spécifier une ou plusieurs adresses IP des appelants (par exemple, des serveurs Web ou des tâches Cron) 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 le format 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 seulement. Lorsque vous créez ou mettez à jour une clé API, indiquez le nom de package et l'empreinte SHA-1 de 20 octets pour chaque application.

Par exemple, supposons que vous ayez exécuté l'utilitaire keytool et créé l'empreinte 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 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 pour iOS

Vous pouvez restreindre l'utilisation d'une clé API à vos applications iOS uniquement en fournissant l'ID de groupe de chaque application lors de la création ou de la mise à jour d'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 d'API vous permettent de spécifier quelles API Google Cloud peuvent être appelées à l'aide de la clé API. Nous vous recommandons d'ajouter les restrictions client et API à toutes vos clés API.

Vous pouvez spécifier un ou plusieurs services dans les restrictions de l'API. L'exemple suivant montre comment limiter l'utilisation d'une nouvelle clé API uniquement aux 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 projet Cloud, exécutez la commande gcloud services list.

Outre la restriction de la clé API à utiliser pour 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 restreindre la clé précédente aux seules 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"
  }'