Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

開始使用 Google Auth Library

總覽

Google Auth Library 是 Java 適用的開放原始碼驗證用戶端程式庫。本文說明如何使用這個程式庫驗證 Java 應用程式，以便存取 Google Cloud 服務。

本指南將說明如何：

使用 Maven、Gradle 或 Simple Build Tool (SBT)，將必要的 Auth Library 依附元件新增至專案。
使用各種方法進行驗證，重點在於應用程式預設憑證 (ADC)。
設定進階驗證情境，包括 Workload Identity Federation、員工身分聯盟和服務帳戶模擬。
產生並使用縮減範圍的權杖，限制權限。
將憑證與 Google HTTP 用戶端程式庫整合。

本說明文件適用於 Java 開發人員。如需完整的 API 詳細資料，請參閱 Google Auth Library API 說明文件。

Java 專用 Google 驗證程式庫包含四個構件：

google-auth-library-credentials 包含 Google 憑證的基礎類別和介面。
google-auth-library-appengine 包含 App Engine 憑證，並依附於 App Engine SDK。
google-auth-library-oauth2-http 包含各種憑證和公用程式方法，包括取得應用程式預設憑證的功能。此外，也提供伺服器端方法，用於產生縮減範圍的權杖。
google-auth-library-cab-token-generator 提供用戶端方法，用於產生縮減範圍的權杖。

驗證憑證設定

使用外部來源的憑證設定 (例如 JSON、檔案路徑或串流) 時，必須先驗證這些設定。如果向 Google API 或用戶端程式庫提供未經驗證的憑證，用於驗證Google Cloud ，可能會危害系統和資料的安全。

詳情請參閱「外部來源憑證」。預設憑證。

匯入 Auth 程式庫

如要匯入 Auth Library，請使用 com.google.cloud:libraries-bom，或搭配 Maven 或 Gradle 使用 Google Auth Library 物料清單。

Java SDK libraries-bom

如要使用 Auth Library 向 Java SDK 中的用戶端程式庫 (例如 google-cloud-datastore) 進行驗證，請使用 libraries-bom，系統會提取與該用戶端程式庫相容的 Auth Library 版本。

舉例來說，如要使用 pom.xml 透過 Maven 匯入 Auth Library，請按照下列步驟操作：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

如果您不使用 libraries-bom 或其他用戶端程式庫，請直接使用 Google Auth Library 物料清單匯入驗證模組。

Google Auth Library 物料清單

您可以使用 Google Auth Library 物料清單，確保 Auth 模組和相關轉換式依附元件相容。

Maven

請將以下內容新增到您的 pom.xml 檔案中：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

在 <dependencies> 區段中，您可以指定任何需要的驗證模組。舉例來說，如要加入 google-auth-library-oauth2-http 模組，請新增下列 <dependency> 項目：

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

請根據應用程式需求，將範例中的 google-auth-library-oauth2-http 替換為 google-auth-library-credentials 或 google-auth-library-appengine。

Gradle

與 Maven 類似，Gradle 使用者可以使用 google-auth-library-bom 管理依附元件版本，並確保不同 google-auth-library 模組之間的相容性。

如要搭配使用 BOM 和 Gradle，請將 BOM 新增為 platform 依附元件。然後新增所需的 google-auth-library 模組。BOM 可確保您使用的所有模組版本都相容。舉例來說，請在 build.gradle 檔案中加入以下內容：

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

與 Maven 和 Gradle 不同，SBT (Scala 建構工具) 不支援 Maven 材料帳單 (BOM)。因此，使用 Scala 時，您無法匯入 google-auth-library-bom，自動處理 Auth 程式庫模組及其傳遞依附元件的相容版本。

您必須直接將每個必要的子模組新增至 build.sbt 檔案。請務必明確指定並對齊您使用的所有 google-auth-library 模組版本。如果版本不一致，可能會導致遞移依附元件之間發生版本衝突，進而造成應用程式出現非預期行為或執行階段錯誤。

如果使用 SBT，請在依附元件中加入以下指令：

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

Auth 程式庫記錄

Java Auth 程式庫建議使用用戶端程式庫偵錯記錄檔功能。偵錯記錄檔會雜湊處理機密權杖 (例如存取權杖、更新權杖等)，並遮蓋值。Auth 程式庫已停用 java.util.logging 記錄功能，以免外洩機密權杖。

用戶端偵錯記錄檔功能為選擇加入，且需要設定。

偵錯記錄功能可根據記錄層級記錄下列內容：

要求資訊：標頭、網址、方法 (INFO 層級)
回應資訊：標頭、狀態、訊息 (INFO 層級)
回應酬載 (DEBUG 級別)

從 `GoogleCredential` 遷移至 `GoogleCredentials`

google-api-java-client 的 GoogleCredential 已淘汰，建議改用 GoogleCredentials。

使用應用程式預設憑證 (ADC) 例項化 GoogleCredentials。建議做法如下：

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

GoogleCredentials 的使用方式取決於用戶端程式庫：

Cloud 用戶端程式庫：這些程式庫會自動使用應用程式預設憑證 (ADC)，因此您不必在程式碼中提供憑證。
Google API 用戶端程式庫：您必須將 GoogleCredentials 例項化，並傳遞至用戶端。如需範例，請參閱 Google API Java 用戶端指南。

應用程式預設憑證

Google 驗證程式庫提供 Java 的應用程式預設憑證 (ADC) 實作。ADC 可讓您取得授權憑證，以便呼叫 Google API。

如果應用程式需要一致的身分和授權層級，且與使用者無關，請使用 ADC。建議您使用 ADC 授權對 Cloud API 的呼叫，尤其是在 Google Cloud上建構應用程式時。

ADC 也支援 Workload Identity Federation，可讓應用程式存取 Amazon Web Services (AWS)、Microsoft Azure 等外部平台，或任何支援 OpenID Connect (OIDC) 的識別資訊提供者中的 Google Cloud 資源。建議您在非Google Cloud 環境中使用 Workload Identity Federation，這樣就不必在本機下載、管理及儲存服務帳戶私密金鑰。

取得應用程式預設憑證

如要取得應用程式預設憑證，請使用 GoogleCredentials.getApplicationDefault() 或 GoogleCredentials.getApplicationDefault(HttpTransportFactory)。這些方法會傳回應用程式預設憑證，用於識別及授權整個應用程式。

系統會依下列順序搜尋，找出應用程式預設憑證：

GOOGLE_APPLICATION_CREDENTIALS 環境變數指向的憑證檔案。
Google Cloud SDK gcloud auth application-default login 指令提供的憑證。
Google App Engine 內建憑證。
Google Cloud Shell 內建憑證。
Google Compute Engine 內建憑證。
- 如要略過這項檢查，請設定環境變數 NO_GCE_CHECK=true。
- 設定環境變數 GCE_METADATA_HOST=<hostname>，自訂中繼資料伺服器位址。

明確載入憑證

如要從服務帳戶 JSON 金鑰取得憑證，請使用 GoogleCredentials.fromStream(InputStream) 或 GoogleCredentials.fromStream(InputStream, HttpTransportFactory)，如以下程式碼範例所示。

必須先重新整理憑證，才能使用存取權杖。

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

模擬憑證

使用 ImpersonatedCredentials，允許憑證 (主體) 模擬服務帳戶 (目標)。這樣一來，主體就能以目標身分存取資源，而不需要目標的私密金鑰。

如要使用 ImpersonatedCredentials，必須符合下列條件：

主體的專案必須啟用 IAMCredentials API。
主體必須具備目標服務帳戶的 Service Account Token Creator (Identity and Access Management) 角色。

下列程式碼範例會建立 ImpersonatedCredentials。主體的憑證是從應用程式預設憑證 (ADC) 取得。接著，系統會使用產生的 ImpersonatedCredentials，以目標服務帳戶的身分存取 Google Cloud Storage。

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "impersonated-account@project.")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

代理身分的憑證繫結權杖

當應用程式以代理身分執行時 (例如使用 --identity-type=agent-identity 部署的 Cloud Run 服務或工作)，ComputeEngineCredentials 預設會向中繼資料伺服器要求憑證繫結存取權杖和 ID 權杖。繫結權杖會與工作負載的 X.509 憑證繫結，且必須透過相互傳輸層安全標準 (mTLS) 證明擁有相符的私密金鑰。由於該私密金鑰僅供工作負載使用，因此外洩的權杖無法在其他地方使用。

只有在透過 mTLS 傳送要求，且使用相同憑證時，系統才會接受繫結權杖。啟用代理身分時，Java 適用的 Cloud 用戶端程式庫會自動設定 mTLS 並重新載入輪替的工作負載憑證。如果您使用自己的 HTTP 用戶端呼叫 Google API，則必須使用工作負載憑證設定 mTLS，並在執行階段輪替磁碟上的憑證時重新載入憑證。輪替後，新更新的權杖會繫結至新憑證；如果新權杖是透過使用先前憑證建立的 mTLS 連線傳送，API 會拒絕要求並傳回 401 UNAUTHENTICATED。

只有在符合下列所有條件時，程式庫才會要求繫結權杖：

系統透過 GOOGLE_API_CERTIFICATE_CONFIG 環境變數命名的檔案或在預設位置 (/var/run/secrets/workload-spiffe-credentials/) 找到工作負載憑證。
憑證的 SPIFFE ID 屬於代理身分信任網域。
未停用權杖繫結和 mTLS (請參閱「停用權杖繫結」)。

在所有其他環境中，ComputeEngineCredentials 的行為與先前相同，並會傳回未繫結的權杖。

關閉權杖繫結

如需關閉權杖繫結 (請參閱「已知限制」)，請設定下列環境變數：

GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false

環境變數	效果
`GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN`	設為 `false` 即可要求未繫結權杖。
`GOOGLE_API_USE_CLIENT_CERTIFICATE`	如果將這項政策設為 `false`，系統會完全關閉 mTLS，同時關閉權杖繫結。如果只需要未繫結的權杖，建議使用 `GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false`。

值不區分大小寫，且會忽略前後的空白字元。只有 false 會關閉功能，其他值則會保留預設值。

環境變數會套用至整個程序，因此關閉權杖繫結會影響應用程式中所有使用應用程式預設憑證的程式庫，而不僅是需要該憑證的程式庫。如果只有部分目標需要未繫結的 ID 權杖，請改用「要求特定目標的未繫結 ID 權杖」一節所述的個別目標選項。

要求特定目標的未繫結 ID 權杖

繫結的 ID 權杖會在 cnf (x5t#S256) 宣告中包含工作負載憑證指紋。接收服務可以根據 mTLS 握手期間提供的用戶端憑證驗證這項聲明，如果未強制執行憑證繫結，則可忽略這項聲明。

如果 ID 權杖中含有 cnf 宣告，Cloud Run 會自動強制執行憑證繫結。如果使用繫結 ID 權杖呼叫 Cloud Run 服務，必須透過 mTLS 呼叫其 *.mtls.run.app 網址；如果向標準 *.run.app 網址或自訂網域提出要求，但未使用 mTLS，系統會拒絕要求並傳回 401 Unauthorized。

如果您透過非 mTLS 端點 (例如標準 *.run.app 網址) 呼叫強制執行憑證繫結的服務，或者目標端點不需要憑證繫結，請傳遞 IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN，僅針對該目標要求未繫結的 ID 權杖：

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
IdTokenCredentials idTokenCredentials =
    IdTokenCredentials.newBuilder()
        .setIdTokenProvider((IdTokenProvider) credentials)
        .setTargetAudience("https://my-service-12345.us-central1.run.app")
        .setOptions(Arrays.asList(IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN))
        .build();

其他目標的存取權杖和 ID 權杖仍會繫結。只有 ComputeEngineCredentials 支援這個選項，其他 IdTokenProvider 實作項目不會要求繫結 ID 權杖，並會忽略這個選項，因此相同的程式碼也能在代理身分環境外運作。

已知限制

Java 版 Agent Development Kit (ADK) 呼叫 Google API (例如 Vertex AI 的 Gemini) 時，不會使用 mTLS。如果使用繫結權杖 (預設)，這些呼叫會失敗並傳回 com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials。如要解決這個問題，請為使用 Java 版 ADK 的代理設定 GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false。詳情請參閱「在 Cloud Run 驗證代理」。

workload identity federation

Workload Identity Federation 可讓應用程式存取 Amazon Web Services (AWS)、Microsoft Azure 或任何支援 OpenID Connect (OIDC) 的識別資訊提供者資源。 Google Cloud

一般來說，在 Google Cloud 外部執行的應用程式會使用服務帳戶金鑰存取 Google Cloud 資源。使用身分聯盟，工作負載就能模擬服務帳戶。這樣一來，外部工作負載就能直接存取 Google Cloud 資源，免除服務帳戶金鑰帶來的維護和安全負擔。

從 AWS 存取資源

如要從 Amazon Web Services (AWS) 存取 Google Cloud 資源，您必須先設定 Workload Identity Federation。如要進一步瞭解設定程序，請參閱「從 AWS 存取資源」。

在這個過程中，您會產生憑證設定檔。這個檔案包含非機密中繼資料，可指示程式庫如何擷取外部主體權杖，並將其交換為服務帳戶存取權杖。您可以使用 Google Cloud CLI 產生檔案：

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
POOL_ID：workload identity pool ID。
AWS_PROVIDER_ID：AWS 供應商 ID。
SERVICE_ACCOUNT_EMAIL：要模擬的服務帳戶電子郵件地址。

這個範例會在指定的輸出檔案中產生設定檔。

如果您使用的是 AWS IMDSv2，則必須在 gcloud iam workload-identity-pools create-cred-config 指令中新增額外的旗標 --enable-imdsv2：

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

現在，您可以使用 Auth 程式庫，從 AWS 呼叫Google Cloud 資源。

從 Microsoft Azure 存取資源

如要從 Microsoft Azure 存取 Google Cloud 資源，必須先設定 Workload Identity Federation。如要進一步瞭解設定程序，請參閱「從 Azure 存取資源」。

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
POOL_ID：workload identity pool ID。
AZURE_PROVIDER_ID：Azure 供應商 ID。
SERVICE_ACCOUNT_EMAIL：要模擬的服務帳戶電子郵件地址。

這個指令會在指定的輸出檔案中產生設定檔。

現在可以使用 Auth 程式庫，從 Azure 呼叫 Google Cloud資源。

從 OIDC 識別資訊提供者存取資源

如要從支援 OpenID Connect (OIDC) 的識別資訊提供者存取 Google Cloud 資源，您必須先設定 Workload Identity Federation，詳情請參閱「透過 OIDC 識別資訊提供者設定 Workload Identity Federation」。

在這個過程中，您會使用 Google Cloud CLI 產生憑證設定檔。這個檔案包含非機密中繼資料，可指示程式庫如何擷取外部主體權杖，並將其交換為服務帳戶存取權杖。

如果是 OIDC 供應商，Auth 程式庫可以從本機檔案 (檔案來源憑證)、本機伺服器 (網址來源憑證) 或 X.509 憑證和私密金鑰組合 (X.509 憑證來源憑證) 擷取 OIDC 權杖。

檔案來源憑證

如果是檔案來源憑證，背景程序必須在到期前，持續以新的 OIDC 權杖重新整理檔案位置。如果權杖的效期為一小時，您必須每小時更新檔案中的權杖。您可以直接以純文字或 JSON 格式儲存權杖。

如要產生檔案來源 OIDC 設定，請執行下列指令：

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
POOL_ID：workload identity pool ID。
OIDC_PROVIDER_ID：OIDC 提供者 ID。
SERVICE_ACCOUNT_EMAIL：要模擬的服務帳戶電子郵件地址。
PATH_TO_OIDC_ID_TOKEN：用於擷取 OIDC 權杖的路徑。

這個指令會在指定的輸出檔案中產生設定檔。

網址來源憑證

如果是網址來源憑證，本機伺服器必須託管 GET 端點，以純文字或 JSON 格式提供 OIDC 權杖。如果端點有要求，您可以指定要在權杖要求中傳送的其他 HTTP 標頭。

如要產生網址來源 Workload Identity 設定，請執行下列指令：

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
POOL_ID：workload identity pool ID。
OIDC_PROVIDER_ID：OIDC 提供者 ID。
SERVICE_ACCOUNT_EMAIL：要模擬的服務帳戶電子郵件地址。
URL_TO_GET_OIDC_TOKEN：呼叫本機伺服器端點來擷取 OIDC 權杖時，所使用的網址。
HEADER_KEY 和 HEADER_VALUE：額外的標頭鍵和值組合，用於將 GET 要求傳遞至 URL_TO_GET_OIDC_TOKEN，例如 Metadata-Flavor=Google。

現在，您可以使用 Auth 程式庫，從 OIDC 供應商呼叫Google Cloud 資源。

使用 X.509 憑證來源憑證存取資源

如果是 X.509 憑證來源憑證，驗證程式庫會使用 X.509 憑證和私密金鑰證明應用程式的身分。X.509 憑證有到期日，必須在到期前更新，才能維持存取權。

詳情請參閱官方說明文件。

產生 X.509 聯盟的設定檔

如要設定 X.509 憑證來源憑證，請產生兩個獨立檔案：主要憑證設定檔和憑證設定檔。

主要憑證設定檔包含驗證所需的中繼資料。這個檔案也會參照憑證設定檔。
憑證設定檔會指定 X.509 憑證、私密金鑰和信任鏈結的檔案路徑。

gcloud iam workload-identity-pools create-cred-config 指令可用於建立這兩者。

gcloud 建立憑證設定檔的位置，取決於您是否使用 --credential-cert-configuration-output-file 旗標。

預設行為 (建議)

如果省略 --credential-cert-configuration-output-file 旗標，gcloud 會在 Auth 程式庫可自動探索的預設已知位置建立憑證設定檔。這個方法適用於大多數用途。預設憑證設定檔名為 config.json，預設憑證設定檔名為 certificate_config.json。

舉例來說，執行下列指令，使用預設行為建立設定檔：

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
POOL_ID：workload identity pool ID。
PROVIDER_ID：供應商 ID。
SERVICE_ACCOUNT_EMAIL：要模擬的服務帳戶電子郵件地址。
PATH_TO_CERTIFICATE：葉 X.509 憑證所在的路徑。
PATH_TO_PRIVATE_KEY：分葉憑證對應私密金鑰所在的路徑。
PATH_TO_TRUST_CHAIN：X.509 憑證信任鏈檔案的路徑。這個檔案應為 PEM 格式，內含完成信任鏈結所需的中繼憑證，該鏈結位於分葉憑證和 Workload Identity Federation 集區中設定的信任存放區之間。這個檔案中的分葉憑證為選用。

這個指令會產生下列結果：

/path/to/config.json：在您指定的路徑建立。這個檔案會包含 "use_default_certificate_config": true，指示用戶端在預設路徑中尋找憑證設定。
certificate_config.json：在預設 Google Cloud CLI 設定路徑建立，通常是 Linux 和 macOS 上的 ~/.config/gcloud/certificate_config.json，或 Windows 上的 %APPDATA%\gcloud\certificate_config.json。

自訂位置行為

如要將憑證設定檔儲存在非預設位置，請使用 --credential-cert-configuration-output-file 旗標。

指令範例 (自訂位置)：

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

這個指令會產生以下結果：

/path/to/config.json：在您指定的路徑建立。這個檔案會包含指向自訂路徑的 "certificate_config_location" 欄位。
cert_config.json：在 /custom/path/cert_config.json 建立，如旗標所指定。

現在，您可以使用 Auth 程式庫，透過 X.509 憑證來源憑證呼叫Google Cloud 資源。

搭配使用可執行檔來源憑證與 OIDC 和 SAML

如果是可執行檔來源憑證，系統會使用本機可執行檔擷取第三方權杖。執行檔必須以 JSON 格式，向 stdout 提供有效且未過期的 OIDC ID 權杖或 SAML 斷言。

如要使用可執行檔來源憑證，GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境變數必須設為 1。

如要產生可執行檔來源 Workload Identity 設定，請執行下列指令：

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
POOL_ID：workload identity pool ID。
PROVIDER_ID：OIDC 或 SAML 提供者 ID。
SERVICE_ACCOUNT_EMAIL：要模擬的服務帳戶電子郵件地址。
SUBJECT_TOKEN_TYPE：主體權杖類型。
EXECUTABLE_COMMAND：要執行的完整指令，包括引數。必須是程式的絕對路徑。

--executable-timeout-millis 旗標為選用，可指定 Auth 程式庫等待執行檔完成的時間長度 (以毫秒為單位)。如未提供，則預設為 30 秒。允許的最大值為兩分鐘，最小值為五秒。

選用的 --executable-output-file 旗標會指定路徑，用於快取執行檔的第三方憑證回應。快取有助於提升效能，因為驗證程式庫會先檢查這個檔案，確認憑證有效且未過期，然後才執行可執行檔。如果存在有效的快取憑證，程式庫就會使用這些憑證，避免不必要的執行檔執行。

可執行檔必須將憑證回應寫入這個檔案。驗證程式庫只會從這個位置讀取。檔案內容必須符合預期的 JSON 格式。

為擷取第三方權杖，程式庫會使用指定指令執行可執行檔。執行檔的輸出內容必須符合下列範例中指定的回應格式，且必須將回應輸出至 stdout。

以下是成功執行 OIDC 的回應範例：

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

以下是可執行的 SAML 回應範例：

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

在憑證設定中使用 --executable-output-file 引數指定輸出檔案時，成功的可執行檔回應必須包含 expiration_time 欄位。這樣 Auth Library 就能有效快取及管理該檔案中儲存的憑證效期。

以下是可執行錯誤回應範例：

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

這些都是錯誤回應的必填欄位。程式庫會使用程式碼和訊息欄位，做為擲回例外狀況的一部分。

回應格式欄位摘要： * version：JSON 輸出的版本。僅支援第 1 版。* success：如果為 true，回應必須包含第三方權杖和權杖類型。如果在憑證設定中指定了輸出檔案，回應也必須包含 expiration_time 欄位。可執行檔也必須以 0 的結束代碼結束。如果為 false，回應必須包含錯誤代碼和訊息欄位，並以非零值結束。token_type：這個欄位會指定第三方主體權杖類型。必須是 urn:ietf:params:oauth:token-type:jwt、urn:ietf:params:oauth:token-type:id_token 或 urn:ietf:params:oauth:token-type:saml2。* id_token：第三方 OIDC 權杖。* saml_response: 第三方 SAML 回應。 * expiration_time：第三方主體權杖到期時間，以秒為單位 (Unix 紀元時間)。* code：錯誤代碼字串。message：錯誤訊息。

所有回應類型都必須包含 version 和 success 欄位。* 成功的回應必須包含 token_type，以及 id_token 或 saml_response 其中之一。如果憑證設定中指定了輸出檔案，則也必須提供 expiration_time 欄位。* 錯誤回應必須同時包含 code 和 message 欄位。

程式庫會在執行可執行檔時，填入下列環境變數：

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE：憑證設定中的目標對象欄位。一律顯示。
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE：預期的主體權杖類型。一律顯示。
GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL：服務帳戶的電子郵件地址。只有在使用服務帳戶模擬功能時，才會顯示這個欄位。
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE：憑證設定的輸出檔案位置。只有在憑證設定中指定時才會顯示。

可執行檔可以使用這些環境變數，避免對這些值進行硬式編碼。

安全性考量

建議採取下列安全性做法：

請防止惡意程序執行可執行檔，因為該檔案會透過 stdout 將機密憑證輸出至這些程序及其使用者。
防止惡意程序修改設定或執行檔的叫用。

由於使用可執行檔來源憑證較為複雜，除非其他支援的機制不符合您的特定需求，否則強烈建議您使用其他支援的機制 (例如檔案或網址來源) 提供第三方憑證。

現在，您可以使用 Auth 程式庫，從 OIDC 或 SAML 供應商呼叫Google Cloud 資源。

使用自訂供應商搭配 OIDC 和 SAML

建構 IdentityPoolCredentials 時，可以使用 IdentityPoolSubjectTokenSupplier 的自訂實作，提供可交換 Google Cloud 存取權杖的主體權杖。當 Google Cloud憑證呼叫供應商時，供應商必須傳回有效且未過期的主體權杖。

IdentityPoolCredentials 不會快取傳回的權杖，因此請在權杖供應器中實作快取邏輯，避免對相同主體權杖提出多項要求。

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

目標對象為：

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
WORKLOAD_POOL_ID：workload identity pool ID。
PROVIDER_ID：供應商 ID。

您也可以使用 gcloud CLI 產生憑證設定檔，找出目標對象、服務帳戶模擬網址和任何其他建構工具欄位的值。

搭配 AWS 使用自訂供應商

初始化 AwsCredentials 時，可以提供 AwsSecurityCredentialsSupplier 的自訂實作。如有提供，AwsCredentials 執行個體會延遲供應商擷取 AWS 安全憑證，以交換Google Cloud 存取權杖。供應商必須在 Google Cloud 憑證呼叫時，傳回有效且未過期的 AWS 安全憑證。

AwsCredentials 不會快取傳回的 AWS 安全憑證或區域，因此請在供應商中實作快取邏輯，避免對相同資源提出多項要求。

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

目標對象： //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
WORKLOAD_POOL_ID：workload identity pool ID。
PROVIDER_ID：供應商 ID。

您也可以使用 gcloud CLI 產生憑證設定檔，找出目標對象、服務帳戶模擬網址和任何其他建構工具欄位的值。

可設定權杖生命週期

使用服務帳戶模擬功能，透過 Workload Identity Federation 建立憑證設定時，您可以提供選用引數，設定服務帳戶存取權杖的生命週期。

如要產生可設定權杖生命週期的設定，請執行下列指令 (本範例使用 AWS 設定，但所有 Workload Identity Federation 提供者都能設定權杖生命週期)：

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

更改下列內容：

PROJECT_NUMBER： Google Cloud 專案編號。
POOL_ID：workload identity pool ID。
AWS_PROVIDER_ID：AWS 供應商 ID。
SERVICE_ACCOUNT_EMAIL：要模擬的服務帳戶電子郵件地址。
TOKEN_LIFETIME：服務帳戶存取權杖的所選生命週期，以秒為單位。

service-account-token-lifetime-seconds 旗標為選用項目。如未提供，旗標預設為一小時。允許的最小值為 600 (10 分鐘)，最大值為 43200 (12 小時)。如果需要超過一小時的生命週期，您必須將服務帳戶新增為組織政策服務中的允許值，該服務會強制執行 constraints/iam.allowServiceAccountCredentialLifetimeExtension 限制。

如果設定較短的生命週期 (例如 10 分鐘)，程式庫就會每 10 分鐘啟動整個權杖交換流程。即使第三方權杖未過期，也會呼叫第三方權杖供應商。

使用外部帳戶授權使用者員工憑證

外部帳戶授權使用者憑證可讓您使用 gcloud CLI，透過網路瀏覽器登入外部身分提供者帳戶，並建立驗證程式庫要使用的設定。

如要產生外部帳戶授權使用者員工身分設定，請執行下列指令：

gcloud auth application-default login --login-config=LOGIN_CONFIG

其中下列變數需要替換：

LOGIN_CONFIG：使用 Google Cloud 控制台或 gcloud iam workforce-pools create-login-config 產生的登入設定檔

系統會開啟瀏覽器流程，讓您使用設定的第三方識別資訊提供者登入。然後將外部帳戶授權使用者設定儲存在已知的 ADC 位置。

Auth 程式庫會使用設定中提供的更新權杖，產生及更新存取權杖，以便呼叫 Google Cloud 服務。

更新權杖的預設效期為一小時。之後，您需要透過 gcloud CLI 產生新的設定。如要修改生命週期，請變更工作團隊集區的工作階段持續時間，最長可設為 12 小時。

使用外部身分

您可以將外部身分與 Application Default Credentials 搭配使用。如要搭配使用外部身分和應用程式預設憑證，請按照「Workload Identity Federation」一節所述，為外部身分產生 JSON 憑證設定檔。產生後，請將這個檔案的路徑儲存在 GOOGLE_APPLICATION_CREDENTIALS 環境變數中。

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

程式庫現在可以選擇正確的用戶端類型，並根據設定檔提供的內容初始化憑證。

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

您也可以使用產生的設定檔，明確初始化外部帳戶用戶端。

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

安全性考量

這個程式庫不會對憑證設定的 token_url、token_info_url 或 service_account_impersonation_url 欄位執行任何驗證。除非您確認網址欄位指向 googleapis.com 網域，否則不建議使用非 gcloud CLI 產生的憑證設定。

透過憑證存取權範圍縮小權限範圍

使用憑證存取權邊界縮減範圍，即可限制短期憑證可用於 Cloud Storage 的 Identity and Access Management (IAM) 權限。這包括建立 CredentialAccessBoundary，定義適用於縮減範圍權杖的限制。使用縮減範圍的憑證，可確保傳輸中的權杖一律具備最小權限。請參閱「最小權限原則」。

建立 `CredentialAccessBoundary`

憑證存取邊界會指定新建立的憑證可以存取哪些資源。此外，也指定了每項資源可用權限的上限。包含一或多個 AccessBoundaryRule 物件。

下列程式碼片段說明如何使用一個 AccessBoundaryRule 初始化 CredentialAccessBoundary。這項規則指定範圍縮減權杖對 bucket bucket-123 中開頭為 customer-a 的物件具有唯讀存取權。

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

常見使用模式

常見的使用模式涉及具有較高存取權的權杖代理。這個代理程式會從存取權限較高的來源憑證，產生範圍縮小的憑證。接著，它會透過安全的驗證管道，將範圍縮小的短期存取權杖傳遞給權杖消費者，以便有限度地存取 Google Cloud儲存空間資源。

產生縮減範圍的權杖

使用 CredentialAccessBoundary 產生縮減範圍權杖的方法有兩種：

伺服器端 (使用 DownscopedCredentials)：用戶端每次需要縮減範圍的權杖時，都會呼叫 Security Token Service (STS)。這項功能適用於憑證存取權邊界規則不常變更，或多次重複使用單一縮小範圍憑證的應用程式。請注意，每次變更規則時，都必須重新呼叫 STS。這個方法可在 google-auth-library-oauth2-http 程式庫中使用，不需要任何額外的依附元件。這可簡化整合程序。如果您的用途不需要用戶端方法的特定優點，這是不錯的選擇。
用戶端 (使用 ClientSideCredentialAccessBoundaryFactory)：用戶端會擷取加密編譯資料一次，然後在本機產生多個縮減範圍的權杖。這樣可以盡量減少對 STS 的呼叫，並在憑證存取權邊界規則頻繁變更時提高效率，因為用戶端不需要在每次規則變更時與 STS 聯絡。如果應用程式需要產生許多不重複的範圍縮減權杖，這種做法也更有效率。google-auth-library-cab-token-generator 模組提供這個方法。不過，這個模組有自己的依附元件。這些依附元件可能會增加專案的複雜度。如果主要考量是盡量減少 STS 呼叫，以及產生大量不重複權杖，請考慮採用這種做法。您也需要管理額外的依附元件。

伺服器端 CAB

DownscopedCredentials 類別可用於從來源憑證和 CredentialAccessBoundary 產生縮減範圍的存取權杖。

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

用戶端 CAB

如果是用戶端 CAB，ClientSideCredentialAccessBoundaryFactory 會與來源憑證搭配使用。初始化工廠後，您可以使用不同的 CredentialAccessBoundary 物件重複呼叫 generateToken() 方法，建立多個範圍縮小的權杖。

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

使用縮減範圍的存取權杖

您可以在私人網路中的伺服器上設定權杖代理程式。同一網路中的各種工作負載 (權杖消費者) 會將經過驗證的要求傳送至該代理，以取得範圍縮小的權杖。這些權杖可讓他們存取或修改特定 Google Cloud 儲存空間 bucket。

代理程式會例項化範圍縮小的憑證例項，可產生短期範圍縮小的存取權杖。然後將這些權杖傳遞給權杖消費者。

權杖消費者可以使用 OAuth2Credentials 或 OAuth2CredentialsWithRefresh，使用這些範圍縮小的存取權杖。接著，您可以使用這組憑證初始化儲存空間用戶端執行個體，存取受限的 Google CloudStorage 資源。

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

只有 Cloud Storage 支援憑證存取權邊界，其他Google Cloud 服務不支援這項功能。

使用 `google-http-client` 的憑證

com.google.auth:google-auth-library-oauth2-http 提供的憑證可與 Google 的 HTTP 用戶端搭配使用。Google 的 HTTP 用戶端提供 HttpCredentialsAdapter，可做為 HttpRequestInitializer，也就是建構工具的最後一個引數。

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

驗證 JWT 權杖 (Beta 版功能)

如要驗證 JWT 權杖，請使用 TokenVerifier 類別。

驗證簽章

如要驗證簽章，請使用預設的 TokenVerifier：

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

自訂`TokenVerifier`

如要自訂 TokenVerifier，請使用建構工具將其實例化：

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

如需更多選項，請參閱 TokenVerifier.Builder 說明文件。

`google-auth-library-credentials`

這個構件包含 Google 憑證的基礎類別和介面：

Credentials：這是授權身分的基礎類別。這個類別的實作項目可以授權您的應用程式。
RequestMetadataCallback：這是回呼的介面，用於接收非同步 Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) 的結果。
ServiceAccountSigner：這是服務帳戶簽署者的介面。這個類別的實作項目能夠使用與 Google 服務帳戶相關聯的憑證簽署位元組陣列。

`google-auth-library-appengine`

這個構件依附於 App Engine SDK (appengine-api-1.0-sdk)。請僅用於在 App Engine 環境中執行且使用 urlfetch 的應用程式。AppEngineCredentials 類別可讓您在提供 AppIdentityService 執行個體的情況下，授權 App Engine 應用程式。

用法：

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

google-auth-library-cab-token-generator

這個模組提供 ClientSideCredentialAccessBoundaryFactory 類別，可讓用戶端使用憑證存取邊界，為 Cloud Storage 產生範圍縮小的權杖。如果應用程式需要頻繁變更憑證存取權邊界規則，或產生許多不重複的縮減範圍權杖，這個方法特別實用，因為能盡量減少對 Security Token Service (STS) 的呼叫。如需使用範例，請參閱「用戶端 CAB」一節。這個模組有自己的依附元件。請評估用戶端縮減範圍的效益，是否大於特定用途增加的複雜度。

開始使用 Google Auth Library 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

驗證憑證設定

匯入 Auth 程式庫

Java SDK libraries-bom

Google Auth Library 物料清單

Maven

Gradle

Scala

Auth 程式庫記錄

從 GoogleCredential 遷移至 GoogleCredentials

應用程式預設憑證

取得應用程式預設憑證

明確載入憑證

模擬憑證

代理身分的憑證繫結權杖

關閉權杖繫結

要求特定目標的未繫結 ID 權杖

已知限制

workload identity federation

從 AWS 存取資源

從 Microsoft Azure 存取資源

從 OIDC 識別資訊提供者存取資源

檔案來源憑證

網址來源憑證

使用 X.509 憑證來源憑證存取資源

產生 X.509 聯盟的設定檔

預設行為 (建議)

自訂位置行為

搭配使用可執行檔來源憑證與 OIDC 和 SAML

安全性考量

使用自訂供應商搭配 OIDC 和 SAML

搭配 AWS 使用自訂供應商

可設定權杖生命週期

使用外部帳戶授權使用者員工憑證

使用外部身分

安全性考量

透過憑證存取權範圍縮小權限範圍

建立 CredentialAccessBoundary

常見使用模式

產生縮減範圍的權杖

伺服器端 CAB

用戶端 CAB

使用縮減範圍的存取權杖

使用 google-http-client 的憑證

驗證 JWT 權杖 (Beta 版功能)

驗證簽章

自訂TokenVerifier

google-auth-library-credentials

google-auth-library-appengine

google-auth-library-cab-token-generator

開始使用 Google Auth Library

從 `GoogleCredential` 遷移至 `GoogleCredentials`

建立 `CredentialAccessBoundary`

使用 `google-http-client` 的憑證

自訂`TokenVerifier`

`google-auth-library-credentials`

`google-auth-library-appengine`