使用經簽署的網址

本頁面簡介已簽署的網址，並說明如何搭配 Cloud CDN 使用。使用已簽署的網址，可將限時的資源存取權提供給任何知道該網址的使用者，且不限於 Google 帳戶擁有者。

已簽署的網址可用來提供有限權限，允許使用者在時限內提出要求。這類網址的查詢字串中包含驗證資訊，可讓不具憑證的使用者對資源執行特定動作。產生已簽署的網址時，您指定的使用者或服務帳戶須具備充分的權限，有權提出與該網址相關的要求。

產生已簽署網址後，任何知道該網址的使用者，都可以用來在指定的一段時間內執行特定動作，例如讀取物件。

已簽署的網址也支援選用的 URLPrefix 參數，可根據通用前置字元提供多個網址的存取權。

如要將存取範圍限制在特定網址前置字元，可考慮使用已簽署的 Cookie。

事前準備

使用已簽署的網址前，請先完成下列步驟：

• 確認已啟用 Cloud CDN；如需操作說明，請參閱「使用 Cloud CDN」。啟用 Cloud CDN 之前，您可以先在後端設定已簽署的網址，但這類網址須等到 Cloud CDN 啟用後才會生效。

• 請視需要更新至最新版 Google Cloud CLI：

  gcloud components update
  

請參閱「已簽署的網址和 Cookie」瞭解概況。

設定已簽署的要求金鑰

如要為已簽署的網址或 Cookie 建立金鑰，請完成以下各節說明的步驟。

安全性考量

在下列情況中，Cloud CDN「不會」驗證要求：

• 要求未經簽署。
• 要求所用的後端服務或後端 bucket 未啟用 Cloud CDN。

已簽署的要求「一律」須先在來源端經過驗證，才能提供回應。這是因為來源可用於提供混合已簽署和未簽署的內容，且用戶端可直接存取來源。

• Cloud CDN 不會封鎖沒有 Signature 查詢參數或 Cloud-CDN-Cookie HTTP Cookie 的要求，且會拒絕要求參數無效 (或格式有誤) 的要求。
• 應用程式偵測到無效簽章時，需確保應用程式會以 HTTP 403 (Unauthorized) 回應代碼回應。HTTP 403 回應代碼不可快取。
• 系統會分別快取已簽署和未簽署要求的回應，因此對有效已簽署要求的成功回應，絕不會用來處理未簽署的要求。
• 如果應用程式將可快取的回應代碼傳送給無效的要求，往後的有效要求可能會遭到拒絕。

如果使用 Cloud Storage 後端，請務必移除公開存取權，Cloud Storage 才能拒絕缺少有效簽章的要求。

下表彙整了相關行為。

建立已簽署的要求金鑰

如要啟用 Cloud CDN 已簽署的網址和 Cookie 支援功能，請在已啟用 Cloud CDN 的後端服務和/或後端 bucket 中，建立一或多組金鑰。

在每個後端服務或後端 bucket 中，依據安全需求建立和刪除金鑰。每個後端一次最多可以設定三組金鑰。建議您定期刪除最舊的金鑰並新增金鑰，然後在簽署網址或 Cookie 時使用新金鑰，藉此輪換金鑰。

各組金鑰彼此不相依，因此可在多個後端服務和後端 bucket 中使用相同的金鑰名稱。金鑰名稱長度上限 63 個字元，如要為金鑰命名，請使用 A-Z、a-z、0-9、_ (底線) 和 - (連字號) 字元。

建立金鑰時，請務必確保金鑰安全，因為任何使用者只要取得其中一組金鑰，就能建立 Cloud CDN 接受的已簽署網址或 Cookie，直到該組金鑰從 Cloud CDN 中刪除為止。金鑰會儲存在您用來產生已簽署網址或 Cookie 的電腦中。另外，Cloud CDN 也會儲存金鑰並用於驗證要求簽章。

為確保金鑰隱密性，請勿在傳送至任何 API 要求的回應中加入金鑰值。如果金鑰遺失，您必須建立新的金鑰。

如要建立已簽署的要求金鑰，請按照下列步驟操作。

head -c 16 /dev/urandom | base64 | tr +/ -_ > KEY_FILE_NAME

gcloud compute backend-services \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

gcloud compute backend-buckets \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

設定 Cloud Storage 權限

如果您使用 Google Cloud Storage，且已限制哪些使用者可以讀取物件，則必須將 Cloud CDN 服務帳戶新增至 Cloud Storage 的 ACL，藉此授予 Cloud CDN 讀取物件的權限。

您不需要建立服務帳戶，首次將金鑰新增至專案後端 bucket 時，系統會自動建立服務帳戶。

執行下列指令前，請先將至少一個金鑰新增至專案中的後端 bucket。若沒有執行這個步驟，指令就會失敗並發生錯誤，因為必須先為專案新增一或多個金鑰，系統才會建立 Cloud CDN 快取填補服務帳戶。

gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member=serviceAccount:service-PROJECT_NUMBER@cloud-cdn-fill.iam.gserviceaccount.com \
  --role=roles/storage.objectViewer

將 PROJECT_NUMBER 替換為專案編號，並將 BUCKET 替換為儲存空間 bucket。

Cloud CDN 服務帳戶 service-PROJECT_NUMBER@cloud-cdn-fill.iam.gserviceaccount.com 不會顯示在專案的服務帳戶清單中。這是因為 Cloud CDN 服務帳戶的擁有者為 Cloud CDN，而非專案。

如要進一步瞭解專案編號，請參閱 Google Cloud 控制台說明文件中的「尋找專案 ID 與專案編號」。

自訂快取時間上限

無論後端的 Cache-Control 標頭為何，Cloud CDN 都會快取已簽署要求的回應。在不重新驗證的情況下快取回應的時間長度上限，是透過 signed-url-cache-max-age 標記設定，預設上限為一小時，不過可以按照下列步驟修改。

如要設定後端服務或後端 bucket 的快取時間長度上限，請執行下列任一指令：

gcloud compute backend-services update BACKEND_NAME \
  --signed-url-cache-max-age MAX_AGE

gcloud compute backend-buckets update BACKEND_NAME \
  --signed-url-cache-max-age MAX_AGE

列出已簽署的要求金鑰名稱

如要列出後端服務或後端 bucket 的金鑰，請執行下列任一指令：

gcloud compute backend-services describe BACKEND_NAME

gcloud compute backend-buckets describe BACKEND_NAME

刪除已簽署的要求金鑰

透過特定金鑰簽署的網址失效之後，請執行下列其中一個指令，從後端服務或後端 bucket 中刪除該組金鑰：

gcloud compute backend-services \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

gcloud compute backend-buckets \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

簽署網址

最後一個步驟是簽署並發布網址。您可以使用 gcloud compute sign-url 指令或自行編寫的程式碼簽署網址。如需大量已簽署的網址，使用自訂程式碼的效果較好。

建立已簽署的網址

請按照下列操作說明，使用 gcloud compute sign-url 指令建立已簽署的網址。此步驟假設您已建立金鑰。

gcloud compute sign-url \
  "URL" \
  --key-name KEY_NAME \
  --key-file KEY_FILE_NAME \
  --expires-in TIME_UNTIL_EXPIRATION \
  [--validate]

gcloud compute sign-url \
  "https://example.com/media/video.mp4" \
  --key-name my-test-key \
  --expires-in 30m \
  --key-file sign-url-key-file

以程式輔助方式建立已簽署的網址

下列程式碼範例示範如何以程式輔助方式建立已簽署的網址。

import (
	"crypto/hmac"
	"crypto/sha1"
	"encoding/base64"
	"fmt"
	"io"
	"io/ioutil"
	"os"
	"strings"
	"time"
)

// SignURL creates a signed URL for an endpoint on Cloud CDN.
//
// - url must start with "https://" and should not have the "Expires", "KeyName", or "Signature"
// query parameters.
// - key should be in raw form (not base64url-encoded) which is 16-bytes long.
// - keyName must match a key added to the backend service or bucket.
func signURL(url, keyName string, key []byte, expiration time.Time) string {
	sep := "?"
	if strings.Contains(url, "?") {
		sep = "&"
	}
	url += sep
	url += fmt.Sprintf("Expires=%d", expiration.Unix())
	url += fmt.Sprintf("&KeyName=%s", keyName)

	mac := hmac.New(sha1.New, key)
	mac.Write([]byte(url))
	sig := base64.URLEncoding.EncodeToString(mac.Sum(nil))
	url += fmt.Sprintf("&Signature=%s", sig)
	return url
}

def signed_url url:, key_name:, key:, expiration:
  # url        = "URL of the endpoint served by Cloud CDN"
  # key_name   = "Name of the signing key added to the Google Cloud Storage bucket or service"
  # key        = "Signing key as urlsafe base64 encoded string"
  # expiration = Ruby Time object with expiration time

  require "base64"
  require "openssl"
  require "time"

  # Decode the URL safe base64 encode key
  decoded_key = Base64.urlsafe_decode64 key

  # Get UTC time in seconds
  expiration_utc = expiration.utc.to_i

  # Determine which separator makes sense given a URL
  separator = "?"
  separator