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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

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

API キーを使用している場合は、ADC を使用して認証情報を提供する必要はありません。API が API キーを受け入れるかどうかについては、API キーの使用をご覧ください。

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

ADC に認証情報を提供する方法は、コードの実行場所によって異なります。

ローカル開発環境

ユーザー認証情報

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

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

  1. gcloud CLI をインストールして初期化します(まだ行っていない場合)。

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

    gcloud auth application-default login

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

gcloud CLI を使用して ADC に認証情報を提供する場合、次のような制限があります。

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

  • この方法では、認証情報がファイル システム上のファイルに保存されます。ファイル システムにアクセスできるすべてのユーザーがこれらの認証情報を使用できます。これらの認証情報が不要になった場合は、取り消す必要があります。

    gcloud auth application-default revoke
  • Google アカウントにプロジェクトで必要な Identity and Access Management(IAM)ロールがない場合、コードが一部のリソースにアクセスできない場合があります。その場合は、セキュリティ管理者に必要なロールを付与するよう依頼してください。

gcloud 認証情報のタイプ

gcloud auth application-default login コマンドを使用すると、Google アカウントの認証情報を既知の場所に保存し、ADC で使用できますが、これらの認証情報を使用できるのはクライアント ライブラリと ADC だけです。gcloud CLI でコマンドを実行する場合は、gcloud auth login コマンドを使用して gcloud CLI にログインしたときに使用した認証情報を使用します。

通常は、同じアカウントで gcloud CLI にログインして、ADC にユーザー認証情報を提供しますが、別のアカウントを使用することもできます。

gcloud CLI へのログインについては、gcloud CLI の初期化をご覧ください。

サービス アカウント キー

ローカルでの開発にユーザー認証情報を使用できない場合は、サービス アカウント キーを使用できます。サービス アカウント キーを使用すると、余分なリスクが増えるため、可能な限り使用しないようにしてください。

組織のポリシーで、サービス アカウント キーの作成を禁止する制約が設定されている場合、この方法は使用できません。

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

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

  2. GOOGLE_APPLICATION_CREDENTIALS 環境変数にキーの場所を設定します。

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

Cloud Shell や Cloud Code など、Google Cloud クラウドベース開発環境を使用する場合は、ログイン時に指定した認証情報が使用され、必要な承認が管理されます。

コンテナ化された開発環境

コンテナ環境でローカル開発を行う場合は、コンテナで個人の認証情報ファイルを利用できるようにする必要があります。これを行うには、GCP Auth minikube アドオンを使用します。

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

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

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

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

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

組織のポリシーで、サービス アカウントの作成を制限する制約が設定されている場合、この方法で ADC の認証情報を設定することはできません。

Google Cloud コンテナ環境

Google Kubernetes Engine または Anthos を使用してアプリケーションをコンテナ化する場合は、ローカルでの開発に gcloud CLI と ADC を使用するか、ローカル コンテナを使用できます。

Google Cloud コンテナ環境に移行する準備ができたら、環境が認証とサービス アカウントをどのようにサポートするかを理解する必要があります。

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

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

Workload Identity 連携

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

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

サービス アカウント キー

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

組織のポリシーで、サービス アカウント キーの作成を禁止する制約が設定されている場合、この方法は使用できません。

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

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

  2. GOOGLE_APPLICATION_CREDENTIALS 環境変数にキーの場所を設定します。

ADC 設定のトラブルシューティング

ADC の使用時に発生する可能性のある一般的な問題には、次のようなものがあります。

ユーザーの認証情報が機能しない

API リクエストから、「この API でサポートされていないエンドユーザー認証情報」、「API がプロジェクトで有効になっていない」、または「割り当てプロジェクトが設定されていない」などのエラー メッセージが返される場合は、次の情報を確認してください。

Google Cloud APIs には次の 2 種類があります。

  • リソースベースの API。課金と割り当てにアクセスされるリソースに関連付けられたプロジェクトを使用します。

  • クライアント ベースの API。課金と割り当てのリソースにアクセスするアカウントに関連付けられたプロジェクトを使用します。

クライアント ベースの API で Google アカウントの認証情報を使用する場合、アカウントに関連付けられたデフォルトのプロジェクトを請求目的で使用することはできません。

この問題を解決するには、請求先プロジェクトとして別のプロジェクトを使用するように ADC を更新する必要があります。

gcloud auth application-default set-quota-project YOUR_PROJECT

プロジェクトを請求先プロジェクトとして指定するには、serviceusage.services.use IAM 権限が必要です。serviceusage.services.use 権限には、Service Usage ユーザーの IAM ロールに含まれています。プロジェクトに対する serviceusage.services.use 権限がない場合は、セキュリティ管理者か、プロジェクトの Service Usage ユーザーのロールを付与できるプロジェクト オーナーに連絡します。

REST リクエストの場合、ADC から返されるトークンに請求プロジェクトは含まれません。REST リクエストで ADC を使用している場合は、REST リクエストでの割り当てプロジェクトの設定をご覧ください。

認証情報が誤っている

認証情報から適切なアクセス権が提供されない、または見当たらない場合は、ADC で利用可能な認証情報を調べます。ADC が認証情報を確認する順番に調査し、何が問題になっているのか確認します。検討が必要なポイントは次のとおりです。

  • ADC にサービス アカウント キーまたは他の JSON ファイルを使用している場合にのみ、GOOGLE_APPLICATION_CREDENTIALS 環境変数が設定されていることを確認します。Workload Identity を含む他の認証情報よりも、環境変数によって示された認証情報が優先されます。

  • リクエスト対象のプリンシパルに必要な IAM ロールがあることを確認します。ユーザー認証情報を使用している場合は、Google アカウントに関連付けられているメールアドレスにロールを付与する必要があります。サービス アカウントを使用している場合は、そのサービス アカウントに必要なロールが必要です。

  • API リクエストで API キーを指定すると、任意の場所の ADC よりも API キーが優先されます。GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定して、API キーを使用している場合、ADC に指定した認証情報が無視されていることを示す警告が API から返されることがあります。警告を停止するには、GOOGLE_APPLICATION_CREDENTIALS 環境変数の設定を解除します。

認識されない認証情報のタイプ

API リクエストで、「JSON から認証情報を作成中にエラーが発生しました。認識できない認証情報タイプです」というエラーが表示された場合は、有効な認証情報を使用していることを確認してください。クライアント ID ファイルでは、ADC の認証情報を提供できません。

次のステップ