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

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

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

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

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

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

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

ローカル開発環境

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

ユーザー認証情報

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

ユーザー アカウントで ADC を構成する場合は、次の点に注意してください。

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

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

  • ローカル ADC ファイルは、gcloud CLI 構成ではなく、ユーザー アカウントに関連付けられます。別の gcloud CLI 構成に変更すると、gcloud CLI で使用される ID が変更される可能性がありますが、ローカル ADC ファイルや ADC 構成に影響はありません。

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

Google アカウントで ADC を構成する

Google アカウントで ADC を構成するには、Google Cloud CLI を使用します。

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

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

  2. 次のように ADC を構成します。

    gcloud auth application-default login

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

外部 IdP によって管理されているアカウントで ADC を構成する

外部 IdP で管理され、Workforce Identity 連携で連携されているユーザー アカウントの ADC を構成するには、次のようにします。

  1. Workforce Identity 連携を構成します。

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

  2. Workforce Identity 連携を使用するように gcloud CLI を構成します。

    詳細については、Google Cloud アクセス トークンの外部認証情報を交換するをご覧ください。

  3. 次のように ADC を構成します。

    gcloud auth application-default login

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

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

サービス アカウントの認証情報を使用して 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 ファイルのパスに設定します。この変数は現在のシェル セッションにのみ適用されるため、新しいセッションを開く場合は、変数を再度設定する必要があります。

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

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

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

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

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

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

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

Set up authentication:

  1. Create the service account:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Replace SERVICE_ACCOUNT_NAME with a name for the service account.

  2. To provide access to your project and your resources, grant a role to the service account:

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

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • ROLE: the role to grant
  3. To grant another role to the service account, run the command as you did in the previous step.
  4. Grant the required role to the principal that will attach the service account to other resources.

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

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • USER_EMAIL: the email address for a Google Account

GKE または GKE Enterprise

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

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

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

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

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

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

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

Workload Identity 連携

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

ADC の Workload Identity 連携の設定については、他のクラウドとの Workload Identity 連携をご覧ください。

サービス アカウント キー

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

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

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

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

次のステップ