google-cloud-recipe-auth

Google Cloud での認証と認可（IAM）

認証とは、あなたが誰であるかを証明するプロセスです。Google Cloud では、ユーザーやサービスなどの ID であるプリンシパルとして扱われます。これは、認可（何ができるかを判断すること）の前段階です。

使用状況の属性情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の属性情報をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコードでは実行しないでください）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:google-cloud-recipe-auth)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:google-cloud-recipe-auth) を追加してください。

認証

エージェントが確認する質問

具体的な解決策を提示する前に、ユーザーに次の点を確認してください。

1. 誰が、または何が認証を行いますか？（人間の開発者、ローカルスクリプト、本番環境で実行されるアプリケーションなど）
2. コードはどこで実行されていますか？（ローカルのノートパソコン、Compute Engine、 GKE、Cloud Run、または AWS／Azure などの別のクラウド）
3. 対象は何ですか？（Storage／BigQuery などの Google Cloud API、または独自に構築したカスタムアプリケーション）
4. 高レベルのクライアントライブラリを使用していますか？（例：Python、Go、Node.js のライブラリは通常、ADC を自動的に処理します。）

---

人間の認証

ユーザーが Google Cloud にアクセスするには、Google Cloud が認識できる ID が必要です。

ユーザー ID の種類

Google Cloud では、社内の従業員（開発者、管理者、従業員）の ID を設定する方法がいくつか用意されています。

• Google 管理アカウント： Cloud Identity または Google Workspace を使用して、管理対象のユーザーアカウントを作成できます。組織がライフサイクルと設定を管理するため、これらは管理対象アカウントと呼ばれます。
• Cloud Identity または Google Workspace を使用した フェデレーション： フェデレーションによって、ユーザーが既存の ID と認証情報を使って Google サービスにサインインできるようにします。ユーザーは外部 ID プロバイダー（IdP）に対して認証を行いますが、Google Cloud Directory Sync（GCDS）などのツールや、Active Directory、Microsoft Entra ID などの外部の信頼できる情報源を使って、アカウントを Google Cloud と同期する必要があります。
• Workforce Identity Federation： 外部 IdP を使って IAM で従業員を直接認証、認可できます。標準的なフェデレーションとは異なり、既存の IdP から Google Cloud の ID へユーザー ID を同期する必要はありません。同期不要の属性ベースのシングルサインオンに対応しています。

開発者と管理者のアクセス方法

開発や管理の際に、Google Cloud のリソースや API を操作するために使用します。

• Google Cloud Console：主要な ウェブインターフェースです。Google アカウント（Gmail または Google Workspace）を使用して認証します。
• gcloud CLI (gcloud auth login)：CLI 自体を認証し、管理コマンド（例：gcloud compute instances list）を実行できるようにします。ローカルに保存された 認証情報（OAuth 2.0 のリフレッシュトークンなど）を使用します。
• アプリケーションのデフォルト認証情報（ADC）を使用したローカル開発 (gcloud auth application-default login)：これは CLI の認証とは異なります。Google Cloud クライアントライブラリ （Python、Java など）が、ノートパソコンでコードを実行する際に「あなた」として動作するためのローカル JSON ファイルを作成します。
• サービスアカウントの 偽装： セキュリティ上の理由から、開発者はサービスアカウントのキーをダウンロードしないようにしてください。代わりに、人間として認証し（gcloud auth login）、サービスアカウントの偽装を使用して CLI コマンドを実行するか、有効期間の短い認証情報を生成します。これはローカル開発やトラブルシューティングにおける重要なベストプラクティスです。

エンドユーザーと顧客向け

デプロイ済みの Google Cloud 上のウェブアプリケーションに、開発者ではない人がアクセスする必要がある場合に使用します。注：これらはワークフォース ID とは異なります。

• Identity-Aware Proxy（IAP）： ウェブアプリケーションの中央認可レイヤーとして機能します。ウェブリクエストをインターセプトし、ユーザーの ID（Google Workspace、Cloud Identity、または外部プロバイダー経由）を確認してから、アプリケーションへのアクセスを許可します。VPN を使わずに内部アプリを保護したり、顧客向けポータルをセキュリティで保護したりするためによく使用されます。
• Identity Platform：カスタム開発したアプリケーションのコードに、コンシューマー向けのサインイン（メールアドレスとパスワード、電話番号、ソーシャルログイン）を直接追加するための、顧客 ID およびアクセス管理（CIAM）ソリューションです。

---

サービス間認証

本番環境でコードを実行する場合は、人間のユーザーアカウントではなく サービスアカウント を使用してください。

サービスアカウントとサービスエージェント

• サービス アカウント： 人間以外のユーザーを対象とした特別な ID です。独自のメールアドレスを持つ「ロボット ID」のようなものです。
• サービスエージェント： Google が管理するサービスアカウントで、サービス（Pub/Sub など）があなたに代わってリソースにアクセスできるようにします。

ベストプラクティス：サービスアカウントの割り当て

サービスアカウントキー（危険な JSON ファイル）を使用するのではなく、カスタムサービスアカウントを Google Cloud リソースに 割り当てて ください。リソースの環境は、ローカルのメタデータサーバーを介して トークン（有効期間の短いデジタルオブジェクト）を提供します。

• Compute Engine： VM の作成時にサービスアカウントを割り当てます。
• Cloud Run： サービスの設定でサービスアカウントを割り当てます。

特殊なケースと高度なトピック

Kubernetes Engine（GKE）

**GKE 向け Workload Identity Federation **を使用して、Kubernetes の ID を IAM プリンシパル識別子にマッピングします。これにより、特定の Kubernetes ワークロードに特定の Google Cloud API へのアクセスを許可できます。詳しくはこちらをご覧ください。

外部ワークロード（Workload Identity Federation）

Google Cloud 外部（AWS、Azure、オンプレミスなど）で実行されるコードには、キーを使用しないでください。代わりに、Workload Identity Federation を使用して、外部トークン（AWS IAM ロールなど）を有効期間の短い Google Cloud アクセストークンと交換します。

API キー

API キーは、公開データ（Google Maps など）や、複雑な設定を行わずに Gemini モデルをすばやくテストできる Vertex AI Express Mode のような簡易的なアクセスに使用される、暗号化された文字列です。API キーに対応しているサービスであれば、人間とサービス（Cloud Run ベースの AI エージェントなど）の両方が API キーを使用できます。

注：セキュリティリスクを最小限に抑えるため、API キーは特定の API とプロジェクトに 制限 してください。誤って公開されないよう、Secret Manager などのシークレットマネージャーに API キーを保存してください。

OAuth 2.0 アクセススコープ

認可には IAM を使用するのが現在の標準ですが、従来型の Compute Engine VM と GKE ノードプールでは、引き続き IAM とともにアクセススコープに依存しています。VM のスコープが制限されている場合、アタッチされたサービスアカウントに正しい IAM 権限があっても、API 呼び出しに失敗します。アタッチされたサービスアカウントが予期せず失敗する場合は、まずこちらを確認してください。

短期間有効な認証情報

偽装とサービス間の安全な通信を支える仕組みは、IAM Service Account Credentials API です。この API は、有効期間の短いアクセストークン、OpenID Connect（OIDC）ID トークン、または自己署名 JSON Web Token（JWT）を動的に生成するため、静的な認証情報が不要になります。

---

認可

認証の後、Google Cloud は **Identity and Access Management （IAM）**を使用して、認証されたプリンシパルに許可される操作を判断します。

• 許可ポリシー：プリンシパルをロールに結び付け、リソースに対して適用する記録です。
• 事前定義された ロール： roles/storage.objectViewer や roles/bigquery.dataEditor のような、事前に作成されたロールです。まずはこちらの使用を検討してください。
• カスタム ロール： 事前定義されたロールの範囲が広すぎる場合に、特定の権限をまとめてユーザーが定義するロールです。

---

例

人間からサービスへ（ローカルでの Python 開発）

1. 認証：gcloud auth application-default login を実行して、ローカル認証情報（ADC）を作成します。
2. 認可：バケットに対する roles/storage.objectViewer ロールを、自分のメールアドレスに付与します。
3. コード：Python の storage.Client() を使用します。ADC を介してローカル認証情報が自動的に検出されます。注：ADC は特定の順序で検索します。最初に GOOGLE_APPLICATION_CREDENTIALS 環境変数を確認し、次にローカルの gcloud JSON ファイル、最後にアタッチされたサービスアカウントのメタデータサーバーを確認します。

サービス間（Cloud Run から Cloud SQL へ）

1. 認証：カスタムサービスアカウントを Cloud Run サービスにアタッチします。
2. 認可：プロジェクトに対する roles/cloudsql.client ロールを、そのサービスアカウントに付与します。
3. コード：Cloud Run 環境が接続ドライバーにトークンを自動的に提供します。

カスタムアプリケーションの呼び出し（OIDC）

別のサービスから非公開の Cloud Run サービスを呼び出す場合、呼び出し元は Google が署名した OpenID Connect（OIDC）ID トークンを生成し、Authorization: Bearer <TOKEN> ヘッダーに含めて渡します。

---

検証チェックリスト

• ユーザーはコードをローカルで実行していますか？gcloud auth application-default login またはサービスアカウントの偽装を提案します。
• ユーザーはローカルでサービスアカウントキーを使おうとしていますか？強く控えるよう伝え、偽装を推奨します。
• ユーザーは本番環境で実行していますか？キーを使わず、最小権限のカスタムサービスアカウントをアタッチするよう推奨します。
• ユーザーは Compute Engine のデフォルトサービスアカウントに依存していますか？代わりにカスタムサービスアカウントを作成するよう推奨します。
• ユーザーは別のクラウドで実行していますか？Workload Identity Federation を推奨します。
• ユーザーはカスタムアプリを呼び出していますか？OIDC ID トークンを推奨します。
• ユーザーは API キーを制限していますか？適切なAPI キーの制限が設定されているか確認します。

参考資料

• 認証の概要
• ユーザー ID
• アプリケーションのデフォルト認証情報
• サービスアカウントのベストプラクティス