概要
Google Auth Library は、Java 用のオープンソース認証クライアント ライブラリです。このドキュメントでは、このライブラリを使用して Java アプリケーションを認証し、 Cloud de Confiance by S3NS サービスにアクセスする方法について説明します。
このガイドでは、次の方法について説明します。
- Maven、Gradle、または Simple Build Tool(SBT)を使用して、必要な Google 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 またはクライアント ライブラリに提供してCloud de Confiance by S3NS の認証を行うと、システムとデータのセキュリティが侵害される可能性があります。
詳細については、外部ソースの認証情報をご覧ください。
Google Auth ライブラリをインポートする
Google Auth ライブラリをインポートするには、com.google.cloud:libraries-bom を使用するか、Maven または Gradle で Google Auth ライブラリの部品構成表を使用します。
Java SDK libraries-bom
Google Auth Library を使用して Java SDK のクライアント ライブラリ(google-cloud-datastore など)を認証するには、libraries-bom を使用します。これにより、そのクライアント ライブラリと互換性のある Google Auth Library のバージョンが pull されます。
たとえば、pom.xml を使用して Maven で Google 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 部品構成表を使用して Google Auth Library モジュールを直接インポートします。
Google Auth ライブラリの部品構成表
Google Auth Library の部品構成表(BOM)を使用すると、Google Auth Library モジュールと関連する推移的依存関係の互換性を確保できます。
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 モジュールを指定できます。たとえば、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 をインポートして、Google Auth Library モジュールの互換性のあるバージョンとその推移的な依存関係を自動的に処理することはできません。
代わりに、必要な各サブモジュールを 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"
Google Auth ライブラリのロギング
Java 用 Google Auth ライブラリでは、クライアント ライブラリのデバッグ ロギングを使用してロギングすることをおすすめします。デバッグ ロギングでは、センシティブなトークン(access_token、refresh_token など)がハッシュ化され、値がマスクされます。機密トークンの漏洩を防ぐため、Google 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 for Java には、アプリケーションのデフォルト認証情報(ADC)の実装が用意されています。ADC は、Google API を呼び出すための認証情報を取得する方法を提供します。
ユーザーに関係なく、アプリケーションで一貫した ID と認証レベルが必要な場合は、ADC を使用します。Cloud APIs の呼び出しを承認するには、ADC を使用することをおすすめします。特に、 Cloud de Confianceでアプリケーションを構築する場合は、ADC を使用することをおすすめします。
ADC は Workload Identity 連携もサポートしているため、アプリケーションはアマゾン ウェブ サービス(AWS)、Microsoft Azure、OpenID Connect(OIDC)をサポートする任意の ID プロバイダなどの外部プラットフォームから Cloud de Confiance リソースにアクセスできます。Cloud de Confiance 以外の環境では、Workload Identity 連携を使用することをおすすめします。これにより、サービス アカウントの秘密鍵をローカルにダウンロード、管理、保存する必要がなくなります。
アプリケーションのデフォルト認証情報を取得する
アプリケーションのデフォルト認証情報を取得するには、GoogleCredentials.getApplicationDefault() または GoogleCredentials.getApplicationDefault(HttpTransportFactory) を使用します。これらのメソッドは、アプリケーション全体を識別して認可するためのアプリケーションのデフォルト認証情報を返します。
アプリケーションのデフォルト認証情報を検索するために、次の順序で検索されます。
GOOGLE_APPLICATION_CREDENTIALS環境変数によって指定された認証情報ファイル。- Google Cloud SDK の
gcloud auth application-default loginコマンドによって提供される認証情報。 - Google App Engine の組み込み認証情報。
- Cloud de Confiance 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 を使用するには、以下の要件を満たす必要があります。
- プリンシパルのプロジェクトで
IAMCredentialsAPI が有効になっている必要があります。 - プリンシパルには、ターゲット サービス アカウントに対する
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.s3ns.iam.gserviceaccount.com")
.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で失敗します。この問題を回避するには、Java 用 ADK を使用するエージェントにGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=falseを設定します。詳細については、Cloud Run でエージェントを認証するをご覧ください。
Workload Identity 連携
Workload Identity 連携を使用すると、アプリケーションは、アマゾン ウェブ サービス(AWS)、Microsoft Azure、または OpenID Connect(OIDC)をサポートする任意の ID プロバイダから Cloud de Confianceリソースにアクセスできます。
従来、 Cloud de Confiance の外部で実行されているアプリケーションは、サービス アカウント キーを使用して Cloud de Confiance リソースにアクセスしていました。ID 連携を使用すると、ワークロードはサービス アカウントの権限を借用できます。これにより、外部ワークロードは Cloud de Confiance リソースに直接アクセスでき、サービス アカウント キーに関連するメンテナンスとセキュリティの負担が軽減されます。
AWS からリソースにアクセスする
アマゾン ウェブ サービス(AWS)から Cloud de Confiance リソースにアクセスするには、まず 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: Cloud de Confiance プロジェクト番号。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
Java 用 Google Auth ライブラリを使用して、AWS からCloud de Confiance by S3NS リソースを呼び出すことができるようになりました。
Microsoft Azure からリソースにアクセスする
Microsoft Azure から Cloud de Confiance リソースにアクセスするには、まず Workload Identity 連携を構成する必要があります。設定プロセスの詳細については、Azure からリソースにアクセスするをご覧ください。
このプロセスの一環として、認証情報構成ファイルを生成します。このファイルには、外部サブジェクト トークンを取得してサービス アカウント アクセス トークンと交換する方法をライブラリに指示する、機密性のないメタデータが含まれています。このファイルは、Google Cloud CLI を使用して生成できます。
# 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: Cloud de Confiance プロジェクト番号。POOL_ID: Workload Identity プール ID。AZURE_PROVIDER_ID: Azure プロバイダ ID。SERVICE_ACCOUNT_EMAIL: 権限を借用するサービス アカウントのメールアドレス。
このコマンドは、指定された出力ファイルに構成ファイルを生成します。
Java 用 Google 認証ライブラリを使用して、Azure から Cloud de Confianceリソースを呼び出すことができるようになりました。
OIDC ID プロバイダからリソースにアクセスする
OpenID Connect(OIDC)をサポートする ID プロバイダから Cloud de Confiance リソースにアクセスするには、まず OIDC ID プロバイダからの Workload Identity 連携の構成で説明されているように、Workload Identity 連携を構成する必要があります。
このプロセスの一環として、Google Cloud CLI を使用して認証情報構成ファイルを生成します。このファイルには、外部サブジェクト トークンを取得してサービス アカウントのアクセス トークンと交換する方法をライブラリに指示する、機密性のないメタデータが含まれています。
OIDC プロバイダの場合、Google Auth Library for Java は次のいずれかのソースから OIDC トークンを取得できます。
- ローカル ファイル(ファイル提供の認証情報)
- ローカル サーバー(URL 提供の認証情報)
- X.509 証明書と秘密鍵(X.509 証明書をソースとする認証情報)
- アクター委任用のサブジェクト トークンとアクター トークンの両方を含むローカル JSON ファイル(オプションの X.509 クライアント証明書バインディングを含む)
ファイル提供の認証情報
ファイルソースの認証情報の場合、バックグラウンド プロセスは、有効期限が切れる前に新しい 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: Cloud de Confiance プロジェクト番号。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: Cloud de Confiance プロジェクト番号。POOL_ID: Workload Identity プール ID。OIDC_PROVIDER_ID: OIDC プロバイダ ID。SERVICE_ACCOUNT_EMAIL: 権限を借用するサービス アカウントのメールアドレス。URL_TO_GET_OIDC_TOKEN: OIDC トークンを取得するために呼び出すローカル サーバー エンドポイントの URL。HEADER_KEYとHEADER_VALUE: GET リクエストをURL_TO_GET_OIDC_TOKENに渡す追加のヘッダーキーと値のペア(例:Metadata-Flavor=Google)。
Java 用 Google Auth ライブラリを使用して、OIDC プロバイダからCloud de Confiance リソースを呼び出すことができるようになりました。
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 は、Google 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: Cloud de Confiance プロジェクト番号。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に作成されます。
Java 用 Google Auth ライブラリを使用して、X.509 証明書をソースとする認証情報でCloud de Confiance by S3NS リソースを呼び出すことができるようになりました。
アクターの委任を使用してリソースにアクセスする
アクター委任(RFC 8693: OAuth 2.0 Token Exchange で定義)で OIDC Workload Identity 連携を使用するワークロードの場合、Google Auth Library for Java は、サードパーティのサブジェクト トークンとサードパーティのアクター トークンの両方をローカル JSON ファイルから交換します。サブジェクト トークンはリクエストのプリンシパル ID を表し、アクター トークンはサブジェクトに代わって動作するワークロードまたはサービスを表します。
アクター委任は、次の 2 つのモードで使用できます。
- 標準のアクター委任(証明書バインディングなし): Google Auth Library は、標準の TLS を介して Security Token Service(
sts.googleapis.com)とサブジェクト トークンとアクター トークンを交換し、構成されている場合はiamcredentials.googleapis.comを使用してサービス アカウントの権限を借用します。 - アクター委任(mTLS)を使用した証明書バインド トークン: Google Auth Library は、
sts.mtls.googleapis.comとのトークン交換(および、構成されている場合はiamcredentials.mtls.googleapis.comを使用したサービス アカウントの権限借用)中に、相互 TLS(mTLS)を介して X.509 クライアント証明書を提示します。Cloud de Confiance は、トークンの確認(cnf.x5t#S256)クレーム内の SHA-256 証明書フィンガープリントが、mTLS handshake で提示されたリーフ クライアント証明書と一致することを確認し、その証明書に暗号的にバインドされた有効期間の短いアクセス トークンを発行します。
始める前に
Java 用 Google Auth ライブラリを構成する前に、次のものが揃っていることを確認してください。
- アクター委任用に構成された OIDC Workload Identity プールとプロバイダ(アクター プロバイダの完全なリソース名がサブジェクト プロバイダの
--actor-providers構成で認可されている)。必要に応じて、証明書バインド トークンを使用する場合は、コンテキストアウェア アクセス ポリシーの適用。 サブジェクト トークンとアクター トークンの両方を含む JSON ファイルを有効期限前に継続的に更新するローカル バックグラウンド プロセス。
{ "subject_token": "<var>SUBJECT_JWT_TOKEN</var>", "actor_token": "<var>ACTOR_JWT_TOKEN</var>" }トークンが次の要件を満たしていることを確認します。
サブジェクト トークン(
may_actクレーム): サブジェクト トークンには、アクターのsub(およびオプションのiss)クレームを承認するmay_actクレームを含める必要があります。"may_act": { "sub": "<var>ACTOR_SUBJECT</var>", "iss": "<var>ACTOR_ISSUER</var>" } ```アクター トークン(
aud、sub、issクレーム): アクター トークンのaudクレームは、アクター プロバイダの完全なリソース名(//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>ACTOR_PROVIDER_ID</var>)に設定する必要があります。また、sub(およびiss)クレームは、サブジェクト トークンのmay_actクレームで宣言された値と一致する必要があります。確認(
cnf)クレーム(証明書バインド トークンのみ): バインドされたトークンの JWT ペイロードには、ワークロードの DER エンコードされた X.509 リーフ証明書の base64url エンコードされた SHA-256 証明書フィンガープリント(x5t#S256)を含むcnfクレームが含まれている必要があります。サブジェクト トークンが証明書にバインドされている場合、アクター トークンも証明書にバインドされている必要があります。また、mTLS handshake で提示されるクライアント証明書は、アクター トークンのcnf.x5t#S256証明書フィンガープリントと一致する必要があります。"cnf": { "x5t#S256": "<var>BASE64URL_SHA256_CERT_FINGERPRINT</var>" } ```
(証明書バインド トークンの場合のみ) PEM でエンコードされた X.509 リーフ証明書ファイルと、ディスク上の一致する暗号化されていない PKCS#8 秘密鍵ファイル。
アクター委任の構成ファイルを生成する
構成ファイルは、gcloud iam workload-identity-pools create-cred-config コマンドを使用して生成できます。
標準のアクター委任(証明書のバインディングなし)
証明書バインディングなしで標準アクター委任の認証情報構成ファイル(config.json)を生成するには、次のコマンドを実行します。
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--output-file /path/to/config.json
アクター委任(mTLS)を使用した証明書バインド トークン
アクター委任を使用して証明書バインド トークンを構成するには、--credential-cert-path フラグと --credential-cert-private-key-path フラグが指定されている場合に、gcloud CLI が 2 つの個別のファイルを生成します。
- プライマリ認証情報構成ファイル(
config.json): Workload Identity プールのメタデータ、.mtls.googleapis.comエンドポイント、JSON トークン ファイルのパス、サブジェクト トークンとアクター トークンのフィールド名、証明書構成ファイルへの参照が含まれます。 - 証明書構成ファイル(
certificate_config.json): ワークロードの X.509 リーフ証明書と秘密鍵のパスを指定します。
--credential-cert-configuration-output-file フラグを省略すると(推奨)、gcloud はデフォルトの Google Cloud CLI 構成パス(Linux と macOS では ~/.config/gcloud/certificate_config.json、Windows では %APPDATA%\gcloud\certificate_config.json)に certificate_config.json を作成し、config.json に "use_default_certificate_config": true を設定します。
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--output-file /path/to/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>OIDC_PROVIDER_ID</var> \
--service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
--credential-source-file "<var>PATH_TO_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--credential-cert-configuration-output-file "/custom/path/certificate_config.json" \
--output-file /path/to/config.json
次のように置き換えます。
PROJECT_NUMBER: Cloud de Confiance プロジェクト番号。POOL_ID: Workload Identity プール ID。OIDC_PROVIDER_ID: サブジェクト トークンを 認証する OIDC Workload Identity プール プロバイダ ID。SERVICE_ACCOUNT_EMAIL: 省略可。権限を借用するサービス アカウントのメールアドレス。リソースへの直接アクセスを使用する場合は、--service-accountを省略します。PATH_TO_TOKENS_JSON: サブジェクト トークンとアクター トークンの両方を含むローカル JSON ファイルのパス。SUBJECT_TOKEN_FIELD_NAME: サブジェクト トークン を含むPATH_TO_TOKENS_JSONの JSON キー(例:subject_token)。ACTOR_TOKEN_FIELD_NAME: アクター トークンを含むPATH_TO_TOKENS_JSONの JSON キー(例:actor_token)。このキーはSUBJECT_TOKEN_FIELD_NAMEとは異なる必要があります。PATH_TO_CERTIFICATE(証明書バインド トークンのみ): PEM エンコードされたリーフ X.509 証明書のパス。PATH_TO_PRIVATE_KEY(証明書バインド トークンのみ): 対応する PEM エンコードされた秘密鍵のパス。
環境変数を構成して Cloud de Confiance API を呼び出す
認証情報の構成ファイルを参照するように
GOOGLE_APPLICATION_CREDENTIALSを設定します。export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json証明書バインド トークンを使用する場合は、
GOOGLE_API_USE_CLIENT_CERTIFICATE=trueを設定して、Cloud クライアント ライブラリでクライアント証明書 mTLS トランスポートを有効にします。export GOOGLE_API_USE_CLIENT_CERTIFICATE=truecertificate_config.jsonをカスタム ロケーションに保存した場合は、GOOGLE_API_CERTIFICATE_CONFIGを設定します。export GOOGLE_API_CERTIFICATE_CONFIG=/custom/path/certificate_config.jsonアプリケーションのデフォルト認証情報を使用して Cloud de Confiance クライアント ライブラリを初期化します。クライアント ライブラリは、
IdentityPoolCredentialsを自動的に使用して、サブジェクト トークンとアクター トークンを交換します(証明書バインディングが構成されている場合は、mTLS 経由でワークロード クライアント証明書を提示します)。import com.google.cloud.pubsub.v1.TopicAdminClient; import com.google.pubsub.v1.ProjectName; import com.google.pubsub.v1.Topic; public class ActorDelegationExample { public static void main(String[] args) throws Exception { String projectId = "your-project-id"; // TopicAdminClient automatically detects GOOGLE_APPLICATION_CREDENTIALS // and uses mTLS when GOOGLE_API_USE_CLIENT_CERTIFICATE=true is set. try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) { for (Topic topic : topicAdminClient.listTopics(ProjectName.of(projectId)).iterateAll()) { System.out.println(topic.getName()); } } } }
トークンと証明書のローテーション
バックグラウンド プロセスがディスク上のトークン(証明書バインド トークンの場合は、ワークロードの X.509 リーフ証明書と秘密鍵)をローテーションする場合は、次の動作と要件に注意してください。
- アトミック更新: Google Auth Library は、更新ごとに 1 回の読み取りで、JSON トークン ファイルからサブジェクト トークンとアクター トークンの両方を読み取ります。サブジェクト トークンとアクター トークンの同期を維持するために、JSON トークン ファイルをアトミックに更新します(たとえば、一時ファイルに書き込んで名前を変更します)。証明書バインド トークンを使用する場合は、証明書、秘密鍵、JSON トークン ファイルをアトミックに更新して、トークン ファイル内の
cnf.x5t#S256サムプリントがディスク上の X.509 証明書と同期された状態を維持します。 - サイクルごとの証明書ピン留め(証明書バインド トークン):
IdentityPoolCredentialsが mTLS 経由でアクセス トークンを更新すると、更新サイクルの開始時に X.509 キーストアのスナップショットを取得し、Security Token ServiceexchangeTokenリクエストと(構成されている場合は)Service Account Credentials APIgenerateAccessTokenの権限借用リクエストの両方で同じクライアント証明書を使用します。 - での自動リロード
401 Unauthorized(証明書バインド トークン): 証明書が ローテーションされ、mTLS リクエストが401 Unauthorizedを返すと、 Google Auth Library はディスクから X.509 証明書と 秘密鍵を自動的にリロードし、トークンの更新を 1 回再試行します。
アクターの委任に関するトラブルシューティング
次の表に、アクター委任に関する一般的なエラーと解決策を示します。
| エラーまたは例外 | 原因 | 解決策 |
|---|---|---|
IllegalArgumentException: Actor tokens are only supported for JSON-formatted credential sources. |
actor_token_field_name が指定されているときに、credential_source.format.type が指定されていないか、text に設定されています。 |
credential_source.format.type を "json" に設定し、subject_token_field_name と actor_token_field_name の両方を指定します。 |
IllegalArgumentException: The actor_token_field_name must not be empty. |
credential_source.format の actor_token_field_name が空の文字列("")です。 |
actor_token_field_name に空でない JSON フィールド名を指定するか、アクター委任を使用しない場合はフィールドを削除してください。 |
IllegalArgumentException: The actor_token_field_name must differ from the subject_token_field_name. |
actor_token_field_name と subject_token_field_name は同じ JSON キーに設定されます。 |
トークン ファイルと config.json で、サブジェクト トークンとアクター トークンに異なる JSON フィールド名を使用します。 |
IllegalArgumentException: An actorTokenType must be specified when an actorTokenSupplier is configured.(またはその逆) |
config.json には actor_token_type または actor_token_field_name のいずれか 1 つのみが存在します。 |
"actor_token_type": "urn:ietf:params:oauth:token-type:jwt" と credential_source.format.actor_token_field_name の両方を指定します。 |
IOException: Invalid token field name. No token was found for field: FIELD_NAME |
credential_source.file の JSON ファイルに、構成された subject_token_field_name キーまたは actor_token_field_name キーが含まれていないか、その値が null です。 |
トークンの更新プロセスで、両方の鍵が JSON ファイルに書き込まれていることを確認します。 |
IOException: Invalid token field value. Empty token was found for field: FIELD_NAME |
JSON トークン ファイルで構成された subject_token_field_name キーまたは actor_token_field_name キーが空であるか、空白文字のみの文字列です。 |
トークンの更新プロセスで、両方のフィールドに空でない JWT 文字列が入力されていることを確認します。 |
IOException: Token field value for FIELD_NAME must be a String... |
JSON トークン ファイルの subject_token_field_name または actor_token_field_name の値が、文字列ではなく JSON オブジェクト、配列、数値、ブール値になっています。 |
両方のトークン フィールドにシリアル化された JWT 文字列("eyJ...")が含まれていることを確認します。 |
RuntimeException: Failed to initialize mTLS transport for file credential source due to certificate configuration error. |
SDK が certificate_config.json、cert_path の X.509 証明書、または key_path の秘密鍵を読み込めなかったか、解析できませんでした。 |
certificate_config.json がデフォルトのパス(または GOOGLE_API_CERTIFICATE_CONFIG)に存在すること、cert_path と key_path が有効で読み取り可能な PEM ファイルを指していることを確認します。 |
400 Bad Request / invalid_request(sts.mtls.googleapis.com) |
トークン内の cnf.x5t#S256 フィンガープリントが、mTLS handshake 中に提示されたクライアント証明書と一致しません。 |
x5t#S256 の値が、certificate_config.json 内の DER エンコードされたリーフ証明書の base64url エンコードされた SHA-256 ハッシュであることを確認します。 |
トークン交換が成功した後に Cloud de Confiance API を呼び出す場合は 401 Unauthorized または 403 Forbidden |
ダウンストリーム クライアント ライブラリが mTLS を確立しなかったか、アクセス トークンにバインドされている証明書とは異なる証明書を使用しました。 | export GOOGLE_API_USE_CLIENT_CERTIFICATE=true が設定されていること、および(カスタム証明書構成パスを使用している場合)GOOGLE_API_CERTIFICATE_CONFIG が config.json で参照されているのと同じ certificate_config.json ファイルを指していることを確認します。 |
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: Cloud de Confiance プロジェクト番号。POOL_ID: Workload Identity プール ID。PROVIDER_ID: OIDC または SAML プロバイダ ID。SERVICE_ACCOUNT_EMAIL: 権限を借用するサービス アカウントのメールアドレス。SUBJECT_TOKEN_TYPE: サブジェクト トークン タイプ。EXECUTABLE_COMMAND: 実行する完全なコマンド(引数を含む)。プログラムへの絶対パスを指定する必要があります。
--executable-timeout-millis フラグは省略可能です。Google Auth Library が実行可能ファイルの終了を待機する時間をミリ秒単位で指定します。指定しない場合、デフォルトの 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 フィールドが含まれている必要があります。これにより、Google 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 ソースなど、サポートされている他のメカニズムを使用してサードパーティの認証情報を提供することを強くおすすめします。
Java 用 Google Auth ライブラリを使用して、OIDC または SAML プロバイダからCloud de Confiance by S3NS リソースを呼び出すことができるようになりました。
OIDC と SAML でカスタム サプライヤーを使用する
IdentityPoolCredentials のビルド中に IdentityPoolSubjectTokenSupplier のカスタム実装を使用して、 Cloud de Confiance アクセス トークンと交換できるサブジェクト トークンを指定できます。サプライヤーは、 Cloud de Confiance認証情報によって呼び出されたときに、有効で期限切れでないサブジェクト トークンを返す必要があります。
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 Cloud de Confiance 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: Cloud de Confiance プロジェクト番号。WORKLOAD_POOL_ID: Workload Identity プール ID。PROVIDER_ID: プロバイダ ID。
オーディエンス、サービス アカウントの権限借用 URL、その他のビルダー フィールドの値は、gcloud CLI で認証情報構成ファイルを生成して確認することもできます。
AWS でカスタム サプライヤーを使用する
AwsCredentials の初期化時に、AwsSecurityCredentialsSupplier のカスタム実装を指定できます。指定すると、AwsCredentials インスタンスはサプライヤーに委任して AWS セキュリティ認証情報を取得し、Cloud de Confiance アクセス トークンと交換します。サプライヤーは、 Cloud de Confiance 認証情報によって呼び出されたときに、有効期限内の有効な 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 Cloud de Confiance 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: Cloud de Confiance プロジェクト番号。WORKLOAD_POOL_ID: Workload Identity プール ID。PROVIDER_ID: プロバイダ ID。
オーディエンス、サービス アカウントの権限借用 URL、その他のビルダー フィールドの値は、gcloud CLI で認証情報構成ファイルを生成して確認することもできます。
構成可能なトークンの有効期間
サービス アカウントの権限借用を使用して 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: Cloud de Confiance プロジェクト番号。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 プロバイダ アカウントにログインし、Google Auth Library で使用する構成を作成できます。
外部アカウントの承認済みユーザーの Workforce Identity 構成を生成するには、次のコマンドを実行します。
gcloud auth application-default login --login-config=LOGIN_CONFIG
次の変数を置き換える必要があります。
LOGIN_CONFIG: Cloud de Confiance コンソールまたは gcloud iam workforce-pools create-login-config で生成されたログイン構成ファイル。
これにより、構成済みのサードパーティ ID プロバイダを使用してログインするためのブラウザフローが開きます。次に、外部アカウントの承認済みユーザー構成を既知の ADC の場所に保存します。
Java 用 Google Auth ライブラリは、構成から提供された更新トークンを使用して、Cloud de Confiance サービスを呼び出すアクセス トークンを生成して更新します。
更新トークンのデフォルトの有効期間は 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();
一般的な使用パターン
一般的な使用パターンでは、昇格されたアクセス権を持つトークン ブローカーが使用されます。このブローカーは、より高いアクセス権を持つソース認証情報から、範囲が限定された認証情報を生成します。次に、範囲が限定された有効期間の短いアクセス トークンを、安全な認証済みチャネルを介してトークン コンシューマに渡し、 Cloud de ConfianceStorage リソースへのアクセスを制限します。
ダウンスコープ トークンを生成する
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 はソース認証情報とともに使用されます。ファクトリを初期化した後、異なる 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);
範囲を絞り込んだアクセス トークンを使用する
プライベート ネットワーク内のサーバーにトークン ブローカーを設定できます。同じネットワーク内のさまざまなワークロード(トークン コンシューマー)が、範囲の限定されたトークンを求める認証済みリクエストをそのブローカーに送信します。これらのトークンを使用すると、特定の Cloud de Confiance Storage バケットにアクセスしたり、変更したりできます。
ブローカーは、有効期間の短い範囲が限定されたアクセス トークンを生成できる、範囲が限定された認証情報インスタンスをインスタンス化します。次に、これらのトークンをトークン コンシューマに渡します。
これらの範囲が限定されたアクセス トークンは、OAuth2Credentials または OAuth2CredentialsWithRefresh を使用してトークン コンシューマーで使用できます。この認証情報を使用してストレージ クライアント インスタンスを初期化し、アクセスが制限された Cloud de ConfianceStorage リソースにアクセスできます。
// 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 のみです。他のCloud de Confiance サービスは、この機能をサポートしていません。
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 セクションをご覧ください。このモジュールには独自の依存関係セットが付属しています。クライアントサイドのダウンスコーピングのメリットが、特定のユースケースで追加される複雑さを上回るかどうかを評価します。