本頁面說明如何使用憑證存取權邊界,建立具有縮減範圍 Cloud Storage 權限的 OAuth 2.0 存取權杖。
建立權限縮減權杖的程序包含下列步驟:
- 將適當的身分與存取權管理角色授予使用者或服務帳戶。
- 定義憑證存取權邊界,設定使用者或服務帳戶可用的權限上限。
- 為使用者或服務帳戶建立 OAuth 2.0 存取權杖。
- 將 OAuth 2.0 存取權杖換成符合憑證存取邊界的新權杖。
接著,您可以使用新的縮減範圍 OAuth 2.0 存取權杖,驗證對 Cloud Storage 的要求。
事前準備
使用憑證存取邊界前,請確認您符合下列需求:
您只需要縮減 Cloud Storage 的權限範圍,不必縮減其他Google Cloud 服務的權限範圍。
如需縮減其他 Google Cloud服務的權限範圍,可以建立多個服務帳戶,並為每個服務帳戶授予不同的角色組合。
您可以使用 OAuth 2.0 存取權杖進行驗證。其他類型的短期憑證不支援憑證存取邊界。
此外,您必須啟用必要的 API:
-
啟用 IAM 和 Security Token Service API (如果尚未啟用)。
啟用 API 所需的角色
如要啟用 API,您必須具備
serviceusage.services.enable權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
授予 IAM 角色
憑證存取邊界會設定資源可用權限的上限。可以減少主體的權限,但無法新增主體尚未擁有的權限。
因此,您也必須在 Cloud Storage bucket 或較高層級的資源 (例如專案) 上,為實體授予所需權限的角色。
舉例來說,假設您需要建立縮減範圍的短期憑證,允許服務帳戶在 bucket 中建立物件:
- 您至少必須將包含
storage.objects.create權限的角色授予服務帳戶,例如 Storage 物件建立者角色 (roles/storage.objectCreator)。憑證存取權邊界也必須包含這項權限。 - 您也可以授予包含更多權限的角色,例如 Storage 物件管理員角色 (
roles/storage.objectAdmin)。服務帳戶只能使用角色授予和憑證存取權邊界中顯示的權限。
如要瞭解 Cloud Storage 的預先定義角色,請參閱「Cloud Storage 角色」。
定義憑證存取邊界
憑證存取權邊界物件包含存取權邊界規則清單。規則由參數組成,可指定使用者或服務帳戶可用的權限上限。如要定義憑證存取權邊界,請建立 JSON 物件,列出存取權邊界規則及其參數。
以下是憑證存取邊界範例:
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:ROLE_ID"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME",
"availabilityCondition": {
"expression" : "CONDITION"
}
}
]
}
}
更改下列內容:
ROLE_ID:預先定義或自訂角色的 ID,定義資源可用權限的上限。例如,roles/storage.objectViewer。如要指定多個角色,請新增一行,並在角色 ID 前加上inRole:前置字元。只有指定角色中的權限可供使用。BUCKET_NAME:規則適用的 Cloud Storage bucket 名稱。CONDITION:選用。條件運算式,指定可使用權限的 Cloud Storage 物件。舉例來說,下列條件會為名稱開頭為customer-a的物件提供權限:resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')
如要進一步瞭解如何建立及自訂憑證存取邊界,請參閱「憑證存取邊界的元件」。
如需憑證存取權邊界的潛在使用案例範例,請參閱「憑證存取權邊界範例」。
建立 OAuth 2.0 存取權杖
建立縮減範圍的短期憑證前,必須先建立一般的 OAuth 2.0 存取權杖。接著,您可以使用一般憑證交換範圍縮小的憑證。建立存取權杖時,請使用 OAuth 2.0 範圍 https://www.googleapis.com/auth/cloud-platform。
如要為服務帳戶建立存取權杖,您可以完成伺服器對伺服器 OAuth 2.0 流程,或使用 Service Account Credentials API 產生 OAuth 2.0 存取權杖。
如要為使用者建立存取權杖,請參閱「取得 OAuth 2.0 存取權杖」。您也可以使用 OAuth 2.0 Playground,為自己的 Google 帳戶建立存取權杖。
交換 OAuth 2.0 存取權杖
建立 OAuth 2.0 存取權杖後,您可以將存取權杖換成符合憑證存取邊界的縮減範圍權杖。這項程序通常涉及「權杖代理程式」和「權杖取用端」:
權杖代理負責定義憑證存取邊界,並將存取權杖交換為縮小範圍的權杖。
權杖代理程式可以使用支援的驗證程式庫自動交換存取權杖,也可以呼叫 Security Token Service 手動交換權杖。
權杖消費者向權杖代理程式要求縮減範圍的存取權杖,然後使用該權杖執行其他動作。
權杖消費者可以使用支援的驗證程式庫,在存取權杖到期前自動重新整理。或者,也可以手動更新權杖,或允許權杖到期而不更新。
有兩種方法可以將存取權杖換成縮減範圍的權杖:
用戶端權杖交換 (建議):用戶端從 Security Token Service API 伺服器取得加密編譯資料。用戶端可使用密碼編譯資料,在用戶端獨立產生具有不同憑證存取權邊界規則的縮減範圍權杖,並設定持續時間 (例如 1 小時)。這種做法可縮短延遲時間並提高效率,特別是對於需要頻繁更新憑證存取權邊界規則的用戶端。如果應用程式需要產生許多不重複的縮減範圍權杖,這種做法也更有效率。建議採用這種做法,因為效能、擴充性和未來功能相容性都較佳。
伺服器端權杖交換:每當憑證存取權邊界規則變更時,用戶端都會向 Security Token Service API 伺服器要求新的縮減範圍權杖。這種做法很簡單,但每次要求縮減範圍的權杖時,都必須往返 Security Token Service API 伺服器。由於每次要求縮減範圍的權杖時,都必須往返 Security Token Service API,因此只有在客戶需要不支援用戶端權杖交換的用戶端程式庫時,才建議採用這種方法。
用戶端權杖交換
如果您使用下列語言建立權杖代理和權杖消費者,則可使用 Google 的驗證程式庫,透過用戶端方法自動交換及更新權杖。
Java
如果是 Java,您可以使用 1.32.1 以上版本的 com.google.auth:google-auth-library-cab-token-generator 構件,自動交換及更新權杖。
如要檢查構件版本,請在應用程式目錄中執行下列 Maven 指令:
mvn dependency:list -DincludeArtifactIds=google-auth-library-cab-token-generator
以下範例說明權杖代理程式如何產生縮減範圍的權杖:
以下範例說明權杖使用者如何使用更新處理常式,自動取得及更新縮減範圍的權杖:
伺服器端權杖交換
本節說明下列方法,可讓您透過服務端方法交換權杖:
使用伺服器端方法自動交換及更新存取權杖
如果您使用下列其中一種語言建立權杖代理和權杖消費者,可以使用 Google 的驗證程式庫,透過伺服器端權杖產生方法自動交換及更新權杖:
Go
如果是 Go,您可以使用 golang.org/x/oauth2 套件 v0.0.0-20210819190943-2bc19b11175f 以上版本,自動交換及更新權杖。
如要檢查套件版本,請在應用程式目錄中執行下列指令:
go list -m golang.org/x/oauth2
以下範例說明權杖代理程式如何產生縮減範圍的權杖:
以下範例說明權杖使用者如何使用更新處理常式,自動取得及更新縮減範圍的權杖:
Java
如果是 Java,您可以使用 1.1.0 以上版本的 com.google.auth:google-auth-library-oauth2-http 構件,自動交換及更新權杖。
如要檢查構件版本,請在應用程式目錄中執行下列 Maven 指令:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
以下範例說明權杖代理程式如何產生縮減範圍的權杖:
以下範例說明權杖使用者如何使用更新處理常式,自動取得及更新縮減範圍的權杖:
Node.js
如果是 Node.js,您可以使用 7.9.0 以上版本的 google-auth-library 套件,自動交換及更新權杖。
如要檢查套件版本,請在應用程式目錄中執行下列指令:
npm list google-auth-library
以下範例說明權杖代理程式如何產生縮減範圍的權杖:
以下範例說明權杖使用者如何提供重新整理處理常式,自動取得及重新整理縮減範圍的權杖:
Python
如果是 Python,您可以使用 2.0.0 以上版本的 google-auth 套件,自動交換及更新權杖。
如要檢查套件版本,請在安裝套件的環境中執行下列指令:
pip show google-auth
以下範例說明權杖代理程式如何產生縮減範圍的權杖:
以下範例說明權杖使用者如何提供重新整理處理常式,自動取得及重新整理縮減範圍的權杖:
手動交換及更新存取權杖
權杖代理程式可以呼叫 Security Token Service API (POST https://sts.googleapis.com/v1/token) 中的 sts.token 方法,將 OAuth 2.0 存取權杖交換為縮減範圍的存取權杖,然後將縮減範圍的權杖提供給權杖使用者。
下列 curl 指令會使用 JSON 格式的憑證存取邊界檔案,交換存取權杖:
curl https://sts.googleapis.com/v1/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--request POST \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
--data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
--data-urlencode "subject_token=ORIGINAL_TOKEN" \
--data-urlencode "options=$(cat ACCESS_BOUNDARY_FILE)"
更改下列內容:
ORIGINAL_TOKEN:要交換的 OAuth 2.0 存取權杖。ACCESS_BOUNDARY_FILE:檔案路徑,其中包含 JSON 格式的憑證存取權邊界,例如./access-boundary.json。
如需要求參數和回應欄位的完整詳細資料,請參閱 sts.token REST API 參考資料。
輸出結果會與下列內容相似:
{
"access_token": "ya29.dr.AbCDeFg-123456...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600
}
只有在原始存取權杖代表服務帳戶時,系統才會顯示 expires_in 欄位。如果原始存取權杖代表使用者帳戶,回應會省略 expires_in,且範圍縮小的權杖會與原始存取權杖同時到期。
當權杖消費者要求縮減範圍的權杖時,權杖代理程式會回覆縮減範圍的權杖,以及權杖到期前的秒數。如果權杖已過期,伺服器會拒絕要求。如要重新整理範圍縮小的權杖,用戶端可以在現有權杖到期前,向代理程式要求範圍縮小的權杖。
後續步驟
- 瞭解 Cloud Storage 的存取控管機制。
- 建立短期服務帳戶憑證。
- 使用下列任一方法,為服務帳戶建立 OAuth 2.0 存取權杖:
- 為使用者建立 OAuth 2.0 存取權杖。
- 查看各預先定義的角色權限。
- 瞭解自訂角色。