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

このページでは、さまざまな環境の 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 に認証情報を提供する方法

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

• ローカル開発環境
• Google Cloud のクラウドベースの開発環境
• Compute Engine、またはサービス アカウントの関連付けをサポートするその他の Google Cloud サービス

• Google Kubernetes Engine

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

ローカル開発環境

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

ユーザー認証情報

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

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

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

• ローカル 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. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   注: Google ドライブなど、Google Cloud 以外のサービスのスコープを追加するには、まず OAuth クライアント ID を作成し、--client-id-file フラグを使用して gcloud auth application-default login コマンドにその ID を渡し、--scopes フラグでスコープを指定します。

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

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

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

1. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command:

   gcloud init

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

   ログイン画面が表示されます。ログインすると、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 ファイルをユーザー認証情報で設定した後と同じ方法で使用できます。認証ライブラリによって認証情報が自動的に検索されます。詳細については、クライアント ライブラリを使用するための認証をご覧ください。

サービス アカウント キー

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

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

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

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

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

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

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

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

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

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

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

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

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

サービス アカウントを接続できるリソースと、サービス アカウントをリソースに接続する方法については、サービス アカウントの接続に関する 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
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
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 または GKE Enterprise で実行されるコンテナ化されたアプリケーションの認証処理は、ローカルテスト環境と Google Cloud 環境で異なります。

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

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

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

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

• GKE Enterprise の場合は、認証の概要と フリート Workload Identity Federation for GKE を使用するをご覧ください。
• GKE の場合は、GKE ワークロードから Google Cloud APIs にアクセスするをご覧ください。
• Knative serving の場合は、Knative serving で Workload Identity Federation for GKE を使用するをご覧ください。

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

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

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

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

次のステップ

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