Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Google Auth ライブラリのスタートガイド

概要

Google Auth Library は、Java 用のオープンソース認証クライアントライブラリです。このドキュメントでは、このライブラリを使用して Java アプリケーションを認証し、 Google Cloud サービスにアクセスする方法について説明します。

このガイドでは、次の方法について説明します。

Maven、Gradle、または Simple Build Tool（SBT）を使用して、必要な Auth ライブラリの依存関係をプロジェクトに追加します。
アプリケーションのデフォルト認証情報（ADC）を中心に、さまざまな方法で認証します。
Workload Identity 連携、Workforce Identity 連携、サービスアカウントの権限借用などの高度な認証シナリオを構成する。
ダウンスコープトークンを生成して使用し、権限を制限する。
認証情報を Google HTTP クライアントライブラリと統合する。

このドキュメントは Java デベロッパーを対象としています。API の詳細については、Google Auth Library API のドキュメントをご覧ください。

Google Auth Library for Java は、次の 4 つのアーティファクトで構成されています。

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 ライブラリをインポートするには、com.google.cloud:libraries-bom を使用するか、Maven または Gradle で Google Auth ライブラリの部品構成表を使用します。

Java SDK libraries-bom

Auth Library を使用して Java SDK のクライアントライブラリ（google-cloud-datastore など）を認証するには、libraries-bom を使用します。これにより、そのクライアントライブラリと互換性のあるバージョンの Auth Library が pull されます。

たとえば、pom.xml を使用して Maven で Auth ライブラリをインポートするには、次のようにします。

<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 Bill of Materials を使用して Auth モジュールを直接インポートします。

Google Auth ライブラリの部品構成表

Google Auth ライブラリの部品構成表（BOM）を使用すると、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> セクションでは、必要な Auth モジュールを指定できます。たとえば、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 モジュール間の互換性を確保できます。

Gradle で BOM を使用するには、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 Build Tool）は 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 ライブラリでは、クライアントライブラリのデバッグロギングを使用してロギングすることをおすすめします。デバッグロギングでは、機密性の高いトークン（access_token、refresh_token など）がハッシュ化され、値がマスクされます。機密性の高いトークンの漏洩を防ぐため、Auth ライブラリでは java.util.logging を使用したロギングが無効になっています。

クライアントデバッグロギング機能はオプトインであり、設定が必要です。

デバッグロギングでは、ログレベルに基づいて次の情報をログに記録できます。

リクエスト情報: ヘッダー、URL、メソッド（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 Auth Library は、Java 用のアプリケーションのデフォルト認証情報（ADC）の実装を提供します。ADC は、Google API を呼び出すための認証情報を取得する方法を提供します。

ユーザーに関係なく、アプリケーションで一貫した ID と認証レベルが必要な場合は、ADC を使用します。Cloud APIs の呼び出しを承認するには、ADC を使用することをおすすめします。特に、 Google Cloudでアプリケーションを構築する場合は、ADC を使用することをおすすめします。

ADC は Workload Identity 連携もサポートしているため、アプリケーションはアマゾンウェブサービス（AWS）、Microsoft Azure、OpenID Connect（OIDC）をサポートする任意の ID プロバイダなどの外部プラットフォームから Google Cloud リソースにアクセスできます。Google Cloud 以外の環境では、Workload Identity 連携を使用することをおすすめします。これにより、サービスアカウントの秘密鍵をローカルにダウンロード、管理、保存する必要がなくなります。

アプリケーションのデフォルト認証情報を取得する

アプリケーションのデフォルト認証情報を取得するには、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);
}

エージェント ID の証明書バインドトークン

アプリケーションがエージェント ID（--identity-type=agent-identity でデプロイされた Cloud Run サービスやジョブなど）で実行されている場合、ComputeEngineCredentials はデフォルトでメタデータサーバーから証明書にバインドされたアクセストークンと ID トークンをリクエストします。バインドされたトークンはワークロードの X.509 証明書に関連付けられており、相互 TLS（mTLS）を介して一致する秘密鍵の所有を証明する必要があります。この秘密鍵はワークロードでのみ使用できるため、漏洩したトークンを他の場所で使用することはできません。

バインドされたトークンは、そのトークンを含むリクエストが同じ証明書を使用して mTLS 経由で送信された場合にのみ受け入れられます。Java 用 Cloud クライアントライブラリは、エージェント ID が有効になっている場合、mTLS を構成し、ローテーションされたワークロード証明書を自動的に再読み込みします。独自の HTTP クライアントを使用して Google API を呼び出す場合は、ワークロード証明書を使用して mTLS を構成し、ランタイムがディスク上の証明書をローテーションするときに再読み込みする必要があります。ローテーション後、新しく更新されたトークンは新しい証明書にバインドされます。以前の証明書で確立された mTLS 接続を介して新しいトークンが送信されると、API は 401 UNAUTHENTICATED でリクエストを拒否します。

ライブラリは、次の条件をすべて満たす場合にのみ、バインドされたトークンをリクエストします。

ワークロード証明書が、GOOGLE_API_CERTIFICATE_CONFIG 環境変数で指定されたファイルまたはデフォルトの場所（/var/run/secrets/workload-spiffe-credentials/）で見つかった。
証明書の SPIFFE ID がエージェント 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 handshake 中に提示されたクライアント証明書に対してこのクレームを検証できます。証明書のバインディングを適用しない場合は、クレームを無視できます。

ID トークンに cnf クレームが存在する場合、Cloud Run は証明書のバインドを自動的に適用します。バインドされた ID トークンを使用して Cloud Run サービスを呼び出す場合は、mTLS 経由で *.mtls.run.app URL を呼び出す必要があります。mTLS を使用しない標準の *.run.app URL またはカスタムドメインへのリクエストは、401 Unauthorized で拒否されます。

mTLS 以外のエンドポイント（標準の *.run.app URL など）で証明書バインディングを適用するサービスを呼び出す場合、またはターゲットエンドポイントに証明書バインディングが必要ない場合は、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 トークンをリクエストせず、このオプションを無視するため、同じコードがエージェント ID 環境外でも機能します。

既知の制限事項

Agent Development Kit（ADK）for Java は、Vertex AI の Gemini などの Google API を呼び出すときに mTLS を使用しません。バインドされたトークン（デフォルト）を使用すると、これらの呼び出しは com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials で失敗します。この問題を回避するには、ADK for Java を使用するエージェントに GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false を設定します。詳細については、Cloud Run でエージェントを認証するをご覧ください。

Workload Identity 連携

Workload Identity 連携を使用すると、アプリケーションは、アマゾンウェブサービス（AWS）、Microsoft Azure、または OpenID Connect（OIDC）をサポートする任意の ID プロバイダから Google Cloudリソースにアクセスできます。

従来、 Google Cloud の外部で実行されているアプリケーションは、サービスアカウントキーを使用して Google Cloud リソースにアクセスしていました。ID 連携を使用すると、ワークロードはサービスアカウントの権限を借用できます。これにより、外部ワークロードは Google Cloud リソースに直接アクセスでき、サービスアカウントキーに関連するメンテナンスとセキュリティの負担が軽減されます。

AWS からリソースにアクセスする

アマゾンウェブサービス（AWS）から Google Cloud リソースにアクセスするには、まず Workload Identity 連携を構成する必要があります。設定プロセスの詳細については、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 プール 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 連携を構成する必要があります。設定プロセスの詳細については、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 プール ID。
AZURE_PROVIDER_ID: Azure プロバイダ ID。
SERVICE_ACCOUNT_EMAIL: 権限を借用するサービスアカウントのメールアドレス。

このコマンドは、指定された出力ファイルに構成ファイルを生成します。

Auth ライブラリを使用して、Azure から Google Cloudリソースを呼び出すことができるようになりました。

OIDC ID プロバイダからリソースにアクセスする

OpenID Connect（OIDC）をサポートする ID プロバイダから Google Cloud リソースにアクセスするには、まず、OIDC ID プロバイダからの Workload Identity 連携の構成で説明されているように、Workload Identity 連携を構成する必要があります。

このプロセスの一環として、Google Cloud CLI を使用して認証情報構成ファイルを生成します。このファイルには、外部サブジェクトトークンを取得してサービスアカウントのアクセストークンと交換する方法をライブラリに指示する、機密性のないメタデータが含まれています。

OIDC プロバイダの場合、Auth ライブラリは、ローカルファイル（ファイルソースの認証情報）、ローカルサーバー（URL ソースの認証情報）、または X.509 証明書と秘密鍵の組み合わせ（X.509 証明書ソースの認証情報）から OIDC トークンを取得できます。

ファイル提供の認証情報

ファイルソースの認証情報の場合、バックグラウンドプロセスは、有効期限が切れる前に、新しい OIDC トークンでファイルの場所を継続的に更新する必要があります。有効期間が 1 時間のトークンの場合、ファイル内のトークンを 1 時間ごとに更新する必要があります。トークンは、書式なしテキストまたは 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 プール ID。
OIDC_PROVIDER_ID: OIDC プロバイダ ID。
SERVICE_ACCOUNT_EMAIL: 権限を借用するサービスアカウントのメールアドレス。
PATH_TO_OIDC_ID_TOKEN: OIDC トークンの取得に使用されるパス。

このコマンドは、指定された出力ファイルに構成ファイルを生成します。

URL 提供の認証情報

URL 提供の認証情報の場合、ローカルサーバーは、書式なしテキストまたは JSON 形式で OIDC トークンを提供する GET エンドポイントをホストする必要があります。エンドポイントで必要な場合は、トークンリクエストで送信する追加の HTTP ヘッダーを指定できます。

URL 提供の OIDC 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 プール ID。
OIDC_PROVIDER_ID: OIDC プロバイダ ID。
SERVICE_ACCOUNT_EMAIL: 権限を借用するサービスアカウントのメールアドレス。
URL_TO_GET_OIDC_TOKEN: OIDC トークンを取得するために呼び出すローカルサーバーエンドポイントの URL。
HEADER_KEY と HEADER_VALUE: URL_TO_GET_OIDC_TOKEN への GET リクエストに渡す追加のヘッダーキーと値のペア（例: Metadata-Flavor=Google）。

Auth ライブラリを使用して、OIDC プロバイダからGoogle Cloud リソースを呼び出すことができるようになりました。

X.509 証明書をソースとする認証情報を使用してリソースにアクセスする

X.509 証明書をソースとする認証情報の場合、認証ライブラリは X.509 証明書と秘密鍵を使用してアプリケーションの ID を証明します。X.509 証明書には有効期限があり、アクセスを維持するには有効期限が切れる前に更新する必要があります。

詳細については、公式ドキュメントをご覧ください。

X.509 連携の構成ファイルを生成する

X.509 証明書をソースとする認証情報を構成するには、プライマリ認証情報構成ファイルと証明書構成ファイルの 2 つのファイルを生成します。

プライマリ認証情報構成ファイルには、認証に必要なメタデータが含まれています。このファイルは、証明書構成ファイルも参照します。
証明書構成ファイルには、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 プール ID。
PROVIDER_ID: プロバイダ ID。
SERVICE_ACCOUNT_EMAIL: 権限を借用するサービスアカウントのメールアドレス。
PATH_TO_CERTIFICATE: リーフ X.509 証明書が配置されているパス。
PATH_TO_PRIVATE_KEY: リーフ証明書の対応する秘密鍵が配置されているパス。
PATH_TO_TRUST_CHAIN: X.509 証明書トラストチェーンファイルのパス。このファイルは、リーフ証明書と Workload Identity 連携プールで構成されたトラストストア間の信頼チェーンを完成させるために必要な中間証明書を含む PEM 形式のファイルにする必要があります。このファイルでは、リーフ証明書は省略可能です。

このコマンドの結果は次のようになります。

/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 で実行可能ファイル提供の認証情報を使用する

実行可能ファイル提供の認証情報の場合、ローカルの実行可能ファイルを使用してサードパーティトークンを取得します。実行可能ファイルは、期限切れでない有効な OIDC ID トークンまたは SAML アサーションを JSON 形式で stdout に提供する必要があります。

実行可能ファイル提供の認証情報を使用するには、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 プール ID。
PROVIDER_ID: OIDC または SAML プロバイダ ID。
SERVICE_ACCOUNT_EMAIL: 権限を借用するサービスアカウントのメールアドレス。
SUBJECT_TOKEN_TYPE: サブジェクトトークンタイプ。
EXECUTABLE_COMMAND: 実行する完全なコマンド（引数を含む）。プログラムへの絶対パスを指定する必要があります。

--executable-timeout-millis フラグは省略可能です。Auth ライブラリが実行可能ファイルの終了を待機する時間（ミリ秒単位）を指定します。指定しない場合、デフォルトの 30 秒が使用されます。最大許容値は 2 分、最小値は 5 秒です。

オプションの --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 ライブラリは、そのファイルに保存されている認証情報の有効性を効果的にキャッシュして管理できます。

実行可能エラーレスポンスの例を次に示します。

{
  "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 を介して、機密性の高い認証情報がそれらのプロセスとそのユーザーに出力されるためです。
不正なプロセスが構成や実行可能ファイルの呼び出しを変更できないようにします。

実行可能ファイルから取得した認証情報を使用するのは複雑なため、特定の要件を満たしていない場合を除き、ファイルや URL ソースなど、サポートされている他のメカニズムを使用してサードパーティの認証情報を提供することを強くおすすめします。

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 プール ID。
PROVIDER_ID: プロバイダ ID。

オーディエンス、サービスアカウントの権限借用 URL、その他のビルダーフィールドの値は、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 プール ID。
PROVIDER_ID: プロバイダ ID。

構成可能なトークンの有効期間

サービスアカウントの権限借用を使用して Workload Identity 連携で認証情報構成を作成するときに、オプションの引数を指定してサービスアカウントのアクセストークンの有効期間を構成できます。

構成可能なトークンの有効期間を使用して構成を生成するには、次のコマンドを実行します（この例では AWS 構成を使用していますが、トークンの有効期間はすべての Workload Identity 連携プロバイダに構成できます）。

  # 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 プール ID。
AWS_PROVIDER_ID: AWS プロバイダ ID。
SERVICE_ACCOUNT_EMAIL: 権限を借用するサービスアカウントのメールアドレス。
TOKEN_LIFETIME: 選択したサービスアカウントのアクセストークンの存続期間（秒単位）。

service-account-token-lifetime-seconds フラグは省略可能です。指定しない場合、このフラグはデフォルトで 1 時間になります。最小許容値は 600（10 分）、最大許容値は 43,200（12 時間）です。1 時間を超える有効期間が必要な場合は、constraints/iam.allowServiceAccountCredentialLifetimeExtension 制約を適用する組織ポリシーサービスの許容値としてサービスアカウントを追加する必要があります。

有効期間を短く（10 分など）構成すると、ライブラリは 10 分ごとにトークン交換フロー全体を開始します。これにより、サードパーティトークンの有効期限が切れていない場合でも、サードパーティトークンプロバイダが呼び出されます。

外部アカウントの承認済みユーザーの Workforce 認証情報を使用する

外部アカウントの承認済みユーザー認証情報を使用すると、gcloud CLI を使用してウェブブラウザで外部 ID プロバイダアカウントにログインし、認証ライブラリで使用する構成を作成できます。

外部アカウントの承認済みユーザーの Workforce Identity 構成を生成するには、次のコマンドを実行します。

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

次の変数を置き換える必要があります。

LOGIN_CONFIG: Google Cloud コンソールまたは gcloud iam workforce-pools create-login-config で生成されたログイン構成ファイル。

ブラウザフローが開き、構成済みのサードパーティ ID プロバイダを使用してログインできます。次に、外部アカウントの承認済みユーザー構成を既知の ADC の場所に保存します。

Auth ライブラリは、構成で指定された更新トークンを使用してアクセストークンを生成して更新し、 Google Cloud サービスを呼び出します。

更新トークンのデフォルトの有効期間は 1 時間です。その後、gcloud CLI から新しい構成を生成する必要があります。有効期間を変更するには、Workforce プールのセッション継続時間を変更します。最大 12 時間まで設定できます。

外部 ID を使用する

Application Default Credentials で外部 ID を使用できます。アプリケーションのデフォルト認証情報で外部 ID を使用するには、Workload Identity 連携セクションの説明に従って、外部 ID の 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 フィールドの検証を行いません。URL フィールドが googleapis.com ドメインを指していることを確認しない限り、gcloud CLI で生成していない認証情報構成を使用することはおすすめしません。

認証情報のアクセス境界によるダウンスコープ

認証情報アクセス境界を使用した範囲の縮小により、有効期間が短い認証情報が Cloud Storage で使用できる Identity and Access Management（IAM）権限を制限できます。これには、ダウンスコープされたトークンに適用される制限を定義する CredentialAccessBoundary を作成する必要があります。ダウンスコープされた認証情報を使用すると、処理中のトークンに常に最小権限が付与されます。最小権限の原則をご覧ください。

`CredentialAccessBoundary` を作成する

認証情報アクセス境界は、新しく作成された認証情報がアクセスできるリソースを指定します。また、各リソースで使用可能な権限の上限も指定します。1 つ以上の AccessBoundaryRule オブジェクトが含まれます。

次のスニペットは、1 つの AccessBoundaryRule で CredentialAccessBoundary を初期化する方法を示しています。このルールでは、ダウンスコープされたトークンに、バケット 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 CloudStorage リソースへのアクセスを制限します。

ダウンスコープトークンを生成する

CredentialAccessBoundary を使用して範囲を限定したトークンを生成する方法は 2 つあります。

サーバーサイド（DownscopedCredentials を使用）: クライアントは、範囲を限定したトークンが必要になるたびに Security Token Service（STS）を呼び出します。これは、認証情報アクセス境界ルールが頻繁に変更されないアプリケーションや、1 つの範囲を限定した認証情報を何度も再利用するアプリケーションに適しています。考慮すべきポイントは、ルールを変更するたびに STS を新たに呼び出す必要があることです。このアプローチは google-auth-library-oauth2-http ライブラリ内で利用でき、追加の依存関係は必要ありません。これにより、統合が簡単になります。ユースケースでクライアントサイドのアプローチの特定のメリットが必要ない場合は、この方法が適しています。
クライアントサイド（ClientSideCredentialAccessBoundaryFactory を使用）: クライアントは暗号マテリアルを 1 回取得し、複数のスコープを縮小したトークンをローカルで生成します。これにより、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 はソース認証情報とともに使用されます。ファクトリを初期化した後、generateToken() メソッドを異なる 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 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 Storage バケットにアクセスしたり、変更したりできます。

ブローカーは、有効期間の短い範囲限定アクセストークンを生成できる範囲限定認証情報インスタンスをインスタンス化します。次に、これらのトークンをトークンコンシューマに渡します。

これらの範囲が限定されたアクセストークンは、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 ベースのクライアントは、HttpRequestInitializer（ビルダーの最後の引数）として使用できる HttpCredentialsAdapter を提供します。

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 トークンを検証する（ベータ版機能）

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: 承認済み ID の基本クラスです。このクラスの実装により、アプリケーションを認可できます。
RequestMetadataCallback: 非同期 Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) の結果を受け取るコールバックのインターフェース。
ServiceAccountSigner: サービスアカウント署名者のインターフェースです。このクラスの実装では、Google サービスアカウントに関連付けられた認証情報を使用してバイト配列に署名できます。

`google-auth-library-appengine`

このアーティファクトは App Engine SDK（appengine-api-1.0-sdk）に依存しています。urlfetch を使用する App Engine 環境で実行されるアプリケーションにのみ使用してください。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 ライブラリのスタートガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

認証情報の構成を検証する

Auth ライブラリをインポートする

Java SDK libraries-bom

Google Auth ライブラリの部品構成表

Maven

Gradle

Scala

Auth ライブラリのロギング

GoogleCredential から GoogleCredentials に移行する

アプリケーションのデフォルト認証情報

アプリケーションのデフォルト認証情報を取得する

明示的な認証情報の読み込み

権限を借用した認証情報

エージェント ID の証明書バインド トークン

トークン バインディングをオフにする

特定のターゲットに対してバインドされていない ID トークンをリクエストする

既知の制限事項

Workload Identity 連携

AWS からリソースにアクセスする

Microsoft Azure からリソースにアクセスする

OIDC ID プロバイダからリソースにアクセスする

ファイル提供の認証情報

URL 提供の認証情報

X.509 証明書をソースとする認証情報を使用してリソースにアクセスする

X.509 連携の構成ファイルを生成する

デフォルトの動作（推奨）

カスタムの場所の動作

OIDC と SAML で実行可能ファイル提供の認証情報を使用する

セキュリティ上の考慮事項

OIDC と SAML でカスタム サプライヤーを使用する

AWS でカスタム サプライヤーを使用する

構成可能なトークンの有効期間

外部アカウントの承認済みユーザーの Workforce 認証情報を使用する

外部 ID を使用する

セキュリティ上の考慮事項

認証情報のアクセス境界によるダウンスコープ

CredentialAccessBoundary を作成する

一般的な使用パターン

ダウンスコープ トークンを生成する

サーバーサイド CAB

クライアントサイドの CAB

範囲を絞り込んだアクセス トークンを使用する

google-http-client で認証情報を使用する

JWT トークンを検証する（ベータ版機能）

署名を検証する

TokenVerifier をカスタマイズする

google-auth-library-credentials

google-auth-library-appengine

google-auth-library-cab-token-generator

Google Auth ライブラリのスタートガイド

`GoogleCredential` から `GoogleCredentials` に移行する

エージェント ID の証明書バインドトークン

トークンバインディングをオフにする

OIDC と SAML でカスタムサプライヤーを使用する

AWS でカスタムサプライヤーを使用する

`CredentialAccessBoundary` を作成する

ダウンスコープトークンを生成する

範囲を絞り込んだアクセストークンを使用する

`google-http-client` で認証情報を使用する

`TokenVerifier` をカスタマイズする

`google-auth-library-credentials`

`google-auth-library-appengine`