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

このページでは、さまざまな環境の Cloud クライアント ライブラリ、Google API クライアント ライブラリ、REST API と RPC API によって使用されるアプリケーションのデフォルト認証情報（ADC）を設定する方法について説明します。ADC を設定するには、コードが実行されている環境で ADC に認証情報を提供します。

Application Default Credentials (ADC) は、アプリケーション環境に基づいて認証情報を自動的に検索するために Google 認証ライブラリが使用するストラテジです。認証ライブラリは、これらの認証情報を Cloud クライアント ライブラリと Google API クライアント ライブラリで使用可能にします。ADC を使用すると、Google Cloud サービスと API に対するアプリケーションの認証方法を変更せずに、開発環境または本番環境でコードを実行できます。

ADC が認証情報を探す場所と順序については、アプリケーションのデフォルト認証情報の仕組みをご覧ください。

API キーを使用している場合は、ADC を設定する必要はありません。詳細については、API キーの使用をご覧ください。

ADC に認証情報を提供する方法

コードが実行されている環境を選択します。

• ローカル開発環境
• Cloud Shell または他の Google Cloud クラウドベースの開発環境
• Compute Engine、またはサービス アカウントの関連付けをサポートするその他の Google Cloud サービス
• Google Kubernetes Engine または GKE Enterprise
• オンプレミスまたは他のクラウド プロバイダ

ローカル開発環境

ローカル開発環境の ADC にユーザー認証情報またはサービス アカウント認証情報を指定できます。

ユーザー認証情報

開発用ワークステーションなどのローカル開発環境でコードを実行している場合は、ユーザー アカウントに関連付けられた認証情報を使用することをおすすめします。

ローカル ADC ファイルを作成するためのユーザー認証情報を提供する場合は、次の点に注意してください。

• ユーザー認証情報は、追加のパラメータや構成がないと、一部のメソッドや API（Cloud Translation API や Cloud Vision API など）で機能しない場合があります。プロジェクトで API が有効になっていないというエラー メッセージが表示された場合、または利用可能な割り当てプロジェクトがない場合は、ADC 設定のトラブルシューティングを行うをご覧ください。

• ローカル ADC には、アクセス トークンと更新トークンが含まれます。ファイル システムにアクセスできるすべてのユーザーがこれらの認証情報を使用できます。これらのローカル認証情報が不要になった場合は、gcloud auth application-default revoke コマンドを使用して取り消すことができます。

• ユーザー アカウントにプロジェクトで必要な Identity and Access Management（IAM）ロールがない場合、コードが一部のリソースにアクセスできない場合があります。この場合、他のユーザーから必要なロールを付与してもらう必要があります。

• ローカル ADC ファイルは、gcloud CLI 構成ではなく、ユーザー アカウントに関連付けられます。別の gcloud CLI 構成に変更しても、ローカル ADC ファイルや ADC に提供される認証情報に影響はありません。

ADC にユーザー認証情報を提供する方法は、ユーザー アカウントが Google によって管理されているか（つまり、Google アカウント）、別の ID プロバイダ（IdP）で管理されていて Workforce Identity 連携で連携されているかによって異なります。

Google アカウントのユーザー認証情報を提供する

Google アカウントのユーザー認証情報を ADC に提供するには、Google Cloud CLI を使用します。

1. gcloud CLI をインストールして初期化します。

   gcloud CLI を初期化するときは、アプリケーションに必要なリソースにアクセスする権限がある Google Cloud プロジェクトを指定してください。

2. 認証情報ファイルを作成します。

   gcloud auth application-default login

   ログイン画面が表示されます。ログインすると、ADC で使用されるローカル認証情報ファイルに認証情報が保存されます。

外部 IdP によって管理されているアカウントのユーザー認証情報を提供する

外部 IdP で管理され、Workforce Identity 連携で連携されているユーザー アカウントのユーザー認証情報を提供するには、Workforce プール プロバイダ名が必要です。この情報は管理者から入手できます。Workforce プール プロバイダの名前の形式は次のとおりです。

locations/global/workforcePools/POOL_ID/provider/PROVIDER_ID

連携されたユーザー アカウントのユーザー認証情報を ADC に提供します。

1. iam workforce-pools create-login-config コマンドを使用して、ログイン構成ファイルを作成し、その場所を指すように gcloud CLI の auth/login_config_file プロパティを設定します。

   gcloud iam workforce-pools create-login-config PROVIDER_ID \
   --output-file=LOGIN_CONFIG_FILE --activate
   

   次のように置き換えます。

   • PROVIDER_ID: プロバイダ ID
   • LOGIN_CONFIG_FILE: 指定した構成ファイルのパス（例: login.json）

   作成されるファイルは次の例のようになります。

   {
   "type": "external_account_authorized_user_login_config",
   "audience": "//iam.googleapis.com/PROVIDER_ID",
   "auth_url": "https://auth.cloud.google/authorize",
   "token_url": "https://sts.googleapis.com/v1/oauthtoken",
   "token_info_url": "https://sts.googleapis.com/v1/introspect",
   }
   

   注意: まず、このファイルの内容が正しいことを確認して、ファイルを保護することをおすすめします。たとえば、ファイルを読み取り専用にし、ACL でのアクセスを制限します。ファイルは検証されません。このファイルへの書き込みアクセス権を持つ悪意のある人物が、エンドポイントを変更して認証情報を傍受する可能性があります。

2. ログイン ファイルを使用して gcloud CLI にログインします。

   gcloud auth login
   

3. gcloud CLI を初期化します。

   gcloud init
   

4. ローカル ADC ファイルを作成します。

   gcloud auth application-default login
   

詳細については、Workforce Identity 連携をご覧ください。

サービス アカウント認証情報

サービス アカウントの認証情報を使用して ADC を設定するには、サービス アカウントの権限借用を使用するか、サービス アカウント キーを使用します。

サービス アカウントの権限借用

サービス アカウントの権限借用を使用して、ローカルのアプリケーションのデフォルト認証情報（ADC）ファイルを設定できます。権限借用をサポートするクライアント ライブラリは、これらの認証情報を自動的に使用できます。権限借用を使用して作成されたローカル ADC ファイルは、次の言語でサポートされています。

• C#
• Go
• Java
• Node.js
• Python

権限を借用するサービス アカウントに対するサービス アカウント トークン作成者（roles/iam.serviceAccountTokenCreator）の IAM ロールが必要です。詳細については、必要なロールをご覧ください。

サービス アカウントの権限借用を使用して、ローカル ADC ファイルを作成します。

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

サービス アカウント キー

ローカル開発でユーザー認証情報やサービス アカウントの権限借用を使用できない場合は、サービス アカウント キーを使用できます。

注: サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

サービス アカウント キーを作成して ADC で使用できるようにするには:

1. サービス アカウント キーの作成の手順に沿って、アプリケーションに必要なロールとサービス アカウント キーを使用して、サービス アカウントを作成します。

2. 環境変数 GOOGLE_APPLICATION_CREDENTIALS を、認証情報を含む JSON ファイルのパスに設定します。この変数は現在のシェル セッションにのみ適用されるため、新しいセッションを開く場合は、変数を再度設定する必要があります。

   例: Linux または macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH は、認証情報が含まれる JSON ファイルのパスに置き換えます。

   例:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   例: Windows

   PowerShell の場合:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH は、認証情報が含まれる JSON ファイルのパスに置き換えます。

   例:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   コマンド プロンプトの場合:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   KEY_PATH は、認証情報が含まれる JSON ファイルのパスに置き換えます。

注: GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定すると、ADC はまずこの場所を確認し、その後は、必要に応じて別の場所も確認します。

Google Cloud のクラウドベースの開発環境

Cloud Shell や Cloud Code など、Google Cloud クラウドベース開発環境を使用する場合は、ログイン時に指定した認証情報が使用され、必要な承認が管理されます。このような環境では、gcloud CLI を使用して ADC に認証情報を指定することはできません。ADC に別のユーザー アカウントを指定する場合、またはサービス アカウントを使用して認証情報を提供する必要がある場合は、ローカル開発環境または Google Cloud コンピューティング リソースを開発環境として使用します。

サービス アカウントの関連付けをサポートする Google Cloud サービス

Compute Engine、App Engine、Cloud Functions など、一部の Google Cloud サービスでは、特定の種類のリソースにユーザー管理のサービス アカウントを関連付けることができます。一般に、サービス アカウントのリソースを指定できるのは、そのサービスのリソースがアプリケーション コードを実行またはインクルードできる場合です。サービス アカウントをリソースに関連付けると、リソースで実行中のコードでそのサービス アカウントを ID として使用できます。

Google Cloud で実行される本番環境コードの認証情報を ADC に提供するには、ユーザー管理のサービス アカウントに関連付けることをおすすめします。

注: これらの Google Cloud サービスの多くは、デフォルトのサービス アカウントも提供しています。デフォルトのサービス アカウントはデフォルトで高い権限を持っているため、デフォルトのサービス アカウントの使用はおすすめしません。これは、最小権限の原則に違反しています。

サービス アカウントに付与する必要があるロールの決定については、事前定義ロールの選択をご覧ください。

サービス アカウントを接続できるリソースと、サービス アカウントをリソースに接続する方法については、サービス アカウントの接続に関する IAM ドキュメントをご覧ください。

認証を設定します。

1. サービス アカウントを作成します。

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   SERVICE_ACCOUNT_NAME をサービス アカウントの名前に置き換えます。

2. プロジェクトとリソースへのアクセス権を付与するには、サービス アカウントにロールを付与します。

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

   次のように置き換えます。

   • SERVICE_ACCOUNT_NAME: サービス アカウントの名前
   • PROJECT_ID: サービス アカウントを作成したプロジェクト ID
   • ROLE: 付与するロール
   注: --role フラグは、サービス アカウントがプロジェクト内のどのリソースにアクセスできるかに影響します。これらのロールは後で取り消すことも、追加のロールを付与することもできます。本番環境では、オーナー、編集者、閲覧者のロールを付与しないでください。代わりに、ニーズに合わせて事前定義ロールまたはカスタムロールを付与します。
3. サービス アカウントに別のロールを付与するには、前の手順で行ったようにコマンドを実行します。

4. サービス アカウントのロールを使用して、そのサービス アカウントを他のリソースに関連付けることができるロールを Google アカウントに付与します。

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

   次のように置き換えます。

   • SERVICE_ACCOUNT_NAME: サービス アカウントの名前
   • PROJECT_ID: サービス アカウントを作成したプロジェクト ID
   • USER_EMAIL: Google アカウントのメールアドレス

GKE または GKE Enterprise

GKE または GKE Enterprise で実行されるコンテナ化されたアプリケーションの認証処理は、ローカルテスト環境と Google Cloud 環境で異なります。

コンテナ化されたアプリケーションをローカルでテストする

ローカル ワークステーションでコンテナ化されたアプリケーションをテストするには、ローカル認証情報ファイルを使用して認証するようにコンテナを構成します。コンテナをテストするには、minikube や gcp-auth アドオンなどのローカル Kubernetes 実装を使用します。

Google Cloud でコンテナ化されたアプリケーションを実行する

Google Cloud コンテナ環境の認証はコンテキストに応じて異なります。

• GKE Enterprise の場合は、認証の概要とフリートの Workload Identity を使用するをご覧ください。
• GKE の場合は、GKE 向け Workload Identity の使用をご覧ください。
• Cloud Run for Anthos については、Cloud Run for Anthos に Workload Identity を使用するをご覧ください。

オンプレミスまたは他のクラウド プロバイダ

Google Cloud の外部でアプリケーションを実行している場合は、Google Cloud サービスを利用するために Google Cloud で認識される認証情報を提供する必要があります。

Workload Identity 連携

別の IdP の認証情報を使用して Google Cloud で認証する場合は、Workload Identity 連携認証情報の構成ファイルを作成し、それを参照するように GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定します。これは、サービス アカウント キーを作成するよりも安全です。

ADC の Workload Identity 連携の設定については、Workload Identity 連携の構成と ID 連携による有効期間の短い認証情報の取得をご覧ください。

サービス アカウント キー

Workload Identity 連携を構成できない場合は、サービス アカウントを作成し、アプリケーションに必要な IAM ロールを付与してから、サービス アカウント キーを作成する必要があります。

注: サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

サービス アカウント キーを作成して ADC で使用できるようにするには:

1. サービス アカウント キーの作成の手順に沿って、アプリケーションに必要なロールとサービス アカウント キーを使用して、サービス アカウントを作成します。

   環境変数 GOOGLE_APPLICATION_CREDENTIALS を、認証情報を含む JSON ファイルのパスに設定します。この変数は現在のシェル セッションにのみ適用されるため、新しいセッションを開く場合は、変数を再度設定する必要があります。

   例: Linux または macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH は、認証情報が含まれる JSON ファイルのパスに置き換えます。

   例:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   例: Windows

   PowerShell の場合:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH は、認証情報が含まれる JSON ファイルのパスに置き換えます。

   例:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   コマンド プロンプトの場合:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   KEY_PATH は、認証情報が含まれる JSON ファイルのパスに置き換えます。

   注: GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定すると、ADC はまずこの場所を確認し、その後は、必要に応じて別の場所も確認します。

次のステップ

• ADC が認証情報を検出する仕組みを確認する。
• Cloud クライアント ライブラリを使用して認証する。
• Google での認証を確認する。