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 ライブラリの API ドキュメントをご覧ください。

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

Java SDK ライブラリ - bom

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

たとえば、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 ライブラリの部品表を使用すると、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 Bills of Materials（BOM）をサポートしていません。そのため、Scala を使用する場合、google-auth-library-bom をインポートして、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"

`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 を使用します。特に Google Cloudでアプリケーションをビルドする場合は、ADC を使用して Cloud APIs の呼び出しを承認することをおすすめします。

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 シェル組み込み認証情報。
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.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);
}

Workload Identity 連携

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

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

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

Amazon Web Services（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 リクエストに渡す追加のヘッダーの Key-Value ペア（例: 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 に設定する必要があります。

実行ファイル提供のワークロード ID 構成を生成するには、次のコマンドを実行します。

# 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();

ここで、audience は次のとおりです。

//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。

gcloud CLI で認証情報構成ファイルを生成することで、オーディエンス、サービスアカウントの権限借用 URL、その他のビルダーフィールドの値を確認することもできます。

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

AwsCredentials を初期化するときに、AwsSecurityCredentialsSupplier のカスタム実装を指定できます。指定された場合、AwsCredentials インスタンスはサプライヤーに委任して、Google Cloud アクセストークンと交換する AWS セキュリティ認証情報を取得します。サプライヤーは、 Google Cloud credential によって呼び出されたときに、期限切れでない有効な 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 アプリケーションを承認できます。

Usage:

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 の範囲が限定されたトークンをクライアントサイドで生成できます。このアプローチは、認証情報アクセス境界ルールの頻繁な変更や、多くのユニークなダウンスコープトークンの生成が必要なアプリケーションに特に役立ちます。セキュリティトークンサービス（STS）への呼び出しを最小限に抑えることができるためです。使用例については、クライアントサイド CAB セクションをご覧ください。このモジュールには、独自の依存関係のセットが付属しています。クライアントサイドのダウンスコープのメリットが、特定のユースケースの複雑さの増加に見合うかどうかを評価します。

Google Auth ライブラリのスタートガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

Java SDK ライブラリ - bom

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

Maven

Gradle

Scala

GoogleCredential から GoogleCredentials に移行する

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

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

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

なりすまされた認証情報

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` に移行する

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

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

`CredentialAccessBoundary` を作成する

範囲が絞り込まれたアクセストークンを使用する

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

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

`google-auth-library-credentials`

`google-auth-library-appengine`