为 API 密钥添加限制

API 密钥向 Google Cloud 标识应用或网站。API 密钥限制可确保只有您的应用和网站可以使用您的密钥。出于安全原因,我们建议您添加的限制如下:

如果客户端使用受限 API 密钥发出不符合 API 密钥限制的请求,则请求会失败。例如,如果 API 密钥要求从特定网域发出 HTTP 请求,但从不同的网域收到 HTTP 请求,请求将被拒绝并报错。

您可以在使用 CreateKey 方法创建 API 密钥时添加限制,也可以在使用 UpdateKey 方法创建密钥后添加限制。本页面介绍了可添加到 API 密钥的限制,并且介绍如何添加这些限制。

准备工作

该页面将 curloauth2l 命令行工具结合使用,以向 API Keys 的 API 发送请求。如需详细了解如何开始使用 API,请参阅 API 密钥使用入门

添加客户端限制

客户端限制用于指定哪些网站、IP 地址或应用可以使用 API 密钥。您可以根据调用 API 的客户端类型添加客户端限制。您可以指定以下某种类型的客户端限制:

  • browserKeyRestrictions:可以使用该密钥的 HTTP 引荐来源网址(网站)。
  • serverKeyRestrictions:可以使用该密钥的调用方的 IP 地址。
  • androidKeyRestrictions:可使用该密钥的 Android 应用。
  • iosKeyRestrictions:可以使用该密钥的 iOS 应用。

添加浏览器限制

以下示例展示了如何调用 UpdateKey 方法将 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"
  }'

当来自 operations.get 的响应包含 "done": true 时,response 包含已更新的 Key,但有限制的限制。

以下示例展示了如何创建仅允许来自特定网址列表的 HTTP 请求的新 API 密钥。

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"]
      }
    }
  }'

下表显示了一些场景和浏览器限制:

场景 限制
允许网站中的任何网址 您必须在“allowedReferers”列表中设置两个网址。
  1. 域名的网址,不带子域名,以及路径的通配符。例如:
    example.com/*
  2. 包含子网域通配符和路径通配符的第二个网址。例如:
    *.example.com/*
允许特定的网址 添加具有确切路径的网址。例如:
www.example.com/path
www.example.com/path/path
允许单个子网域或裸网域中的任何网址 您必须在“allowedReferers”列表中设置两个网址,才能允许整个网域。
  1. 域名,不带斜杠。例如:
    www.example.com
    sub.example.com
    example.com
  2. 包含路径通配符的第二个网址。 例如:
    www.example.com/*
    sub.example.com/*
    example.com/*

添加服务器限制

您可以指定调用方可以使用一个或多个 IP 地址,例如 Web 服务器或 Cron 作业。您可以使用以下任何格式指定 IP 地址:

  • IPv4 (198.51.100.1)
  • IPv6 (2001:db8::1)
  • 使用 CIDR 表示法的子网(198.51.100.0/242001:db8::/64

以下示例演示了如何使用 allowedIps 列表创建 API 密钥:

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"]
      }
    }
  }'

添加 Android 限制

您可以将 API 密钥的使用范围限制为仅限您的 Android 应用。创建或更新 API 密钥时,请提供每个应用的软件包名称和 20 字节 SHA-1 指纹

例如,假设您运行 keytool 实用程序,并创建了以下指纹:

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

以下示例展示了如何创建带有指纹和软件包名称的 API 密钥到 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"
          }
        ]
      }
    }
  }'

添加 iOS 限制

在创建或更新密钥时,您可以通过提供每个应用的软件包 ID,将 API 密钥的使用范围限制为 iOS 应用。以下示例展示了如何在创建 API 密钥时设置 iosKeyRestrictions

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"]
      }
    }
  }'

添加 API 限制

API 限制用于指定可以使用 API 密钥调用哪些 Google Cloud API。我们建议您将所有 API 密钥都同时添加客户端和 API 限制。

您可以在 API 限制中指定一项或多项服务。以下示例展示了如何将新的 API 密钥限制为 translate.googleapis.comdatastore.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"
        }
      ]
    },
  }'

如需获取您的 Cloud 项目中已启用的服务的列表,请使用 gcloud services list 命令。

除了限制用于特定服务的 API 密钥之外,您还可以选择在每个服务中指定方法,以进一步限制 API 密钥。以下示例展示了如何将先前的密钥限制为允许使用的 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"
  }'

后续步骤