新增 API 金鑰限制

API 金鑰會向 Cloud de Confiance by S3NS識別您的應用程式或網站。API 金鑰限制可確保只有您的應用程式和網站可以使用金鑰。基於安全考量，建議您新增限制，指定：

如果用戶端使用受限的 API 金鑰發出要求，但要求不符合 API 金鑰限制，要求就會失敗。舉例來說，如果 API 金鑰要求 HTTP 請求必須從特定網域發出，但系統收到來自其他網域的 HTTP 請求，就會拒絕該請求並傳回錯誤。

使用 CreateKey 方法建立 API 金鑰時，可以新增限制，也可以使用 UpdateKey 方法在金鑰建立後新增限制。本頁說明可新增至 API 金鑰的限制，並示範如何新增這些限制。

新增用戶端限制

用戶端限制會指定哪些網站、IP 位址或應用程式可以使用 API 金鑰。您可以根據呼叫 API 的用戶端類型新增用戶端限制。您可以指定下列其中一種用戶端限制：

  • browserKeyRestrictions：允許使用金鑰的 HTTP 參照網址 (網站)。
  • serverKeyRestrictions：允許使用金鑰的呼叫端 IP 位址。
  • androidKeyRestrictions：允許使用金鑰的 Android 應用程式。
  • iosKeyRestrictions：允許使用金鑰的 iOS 應用程式。

新增瀏覽器限制

以下範例說明如何呼叫 UpdateKey 方法，將 HTTP 參照網址限制為 www.example.com：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "restrictions" : {
            "browserKeyRestrictions": {
              "allowedReferrers": "www.example.com"
            }
          },
          "etag": "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions'

如果 operations.get 的回應包含 "done": true，則 response 會包含更新後的 Key，其中含有限制。

以下範例說明如何建立新的 API 金鑰，只允許來自特定網址清單的 HTTP 要求。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "API key with browser restrictions",
          "restrictions" : {
            "browserKeyRestrictions": {
              "allowedReferrers": ["www.example.com", "www.example-2.com"]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

下表列出一些範例情境和瀏覽器限制：

情境 限制
允許網站中的任何網址 您必須在 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 位址 (例如網頁伺服器或 Cron 工作)，允許這類呼叫端使用您的 API 金鑰。您可以透過下列任一格式指定 IP 位址：

  • IPv4 (198.51.100.1)
  • IPv6 (2001:db8::1)
  • 使用 CIDR 標記法的子網路 (198.51.100.0/24、2001:db8::/64)

下列範例說明如何使用 allowedIps 清單建立 API 金鑰：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "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"]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

新增 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

以下範例說明如何使用指紋和套件名稱，在 androidKeyRestrictions 中建立 API 金鑰：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "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"
                }
              ]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

新增 iOS 限制

建立或更新金鑰時，您可以提供各應用程式的軟體包 ID，限制 API 金鑰只能用於 iOS 應用程式。以下範例說明如何建立 API 金鑰時設定 iosKeyRestrictions：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "API key with iOS restrictions",
          "restrictions" : {
            "iosKeyRestrictions": {
              "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

新增 API 限制

您可以透過 API 限制，指定可使用 API 金鑰呼叫的 API。 Cloud de Confiance by S3NS 建議您為所有 API 金鑰新增用戶端和 API 限制。

您可以在 API 限制中指定一或多項服務。以下範例說明如何限制新 API 金鑰的使用範圍，只允許 translate.googleapis.com 和 datastore.googleapis.com 服務使用：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "API key with API restrictions",
          "restrictions": {
            "api_targets": [
              {
                "service": "translate.googleapis.com"
              },
              {
                "service" : "datastore.googleapis.com"
              }
            ]
          },
        }' \
        'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

如要取得Cloud de Confiance 專案中已啟用的服務清單，請使用 gcloud services list 指令。

除了限制 API 金鑰只能用於特定服務，您也可以選擇指定各服務中的方法，進一步限制 API 金鑰。以下範例說明如何將前一個金鑰限制為僅允許 translate.googleapis.com 的方法：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "restrictions": {
            "api_targets": [
              {
                "service": "translate.googleapis.com",
                "methods": [
                  "Get*",
                  "DetectLanguage"
                ]
              },
              {
                "service" : "datastore.googleapis.com"
              }
            ]
          },
          "etag": "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions'

後續步驟