API キーは、リクエストの認証に使う秘密の認証情報です。サービスアカウントは、アプリケーションや自動化されたワークロードが利用できる、人に紐づかない ID です。サービスアカウントは API キーを所有できます。サービスアカウントがリクエストの主体となり、その認証に API キーを使います。
自分の開発作業には、自分が所有するプロジェクトキーを使います。権限とライフサイクルを個別に管理したいアプリケーションや自動処理には、サービスアカウントを使います。管理 API を通じて組織を管理するには、管理 API キーを使います。
用途に応じた ID の選択
| ワークロード | ID と認証情報 | 選択の理由 |
|---|---|---|
| 自分のローカル環境での開発や試行 | 自分のユーザーアカウントとプロジェクト API キー | 自分がそのプロジェクトに対して持つ権限でリクエストを送信できます。 |
| デプロイ済みのアプリケーション、定期実行ジョブ、CI ワークフロー | プロジェクトのサービスアカウントとその API キー | 個々の開発者から独立した ID をワークロードに割り当てられます。 |
| OpenAI がサポートする ID プロバイダーを使うワークロード | ワークロード ID フェデレーションを使うプロジェクトのサービスアカウント | ワークロードは長期有効な OpenAI API キーを保存せずに認証できます。 |
| プロジェクトの作成や、そのサービスアカウントとキーの管理を行う自動処理 | 管理 API キー | 組織の管理には、管理専用のエンドポイントと権限を使います。 |
ユーザーが所有するキーを使うと、その所有者の権限で操作が実行されます。開発者個人のキーをチームで共有したり、その人の ID を本番アプリケーションの恒久的な ID として使ったりしないでください。
サービスアカウントはプロジェクトに属します。ワークロードごとに、そのプロジェクトで必要な ID とアクセス権を割り当ててください。アプリケーションや環境ごとにプロジェクトを分けると、リソース、メンバー、使用状況を個別に管理できます。同じプロジェクト内でサービスアカウントを分ければ、プロジェクトを追加せずにワークロードを区別できます。
権限とスコープ
API キーで実行できる操作は、キー自体の権限と所有者の権限の両方で決まります。キーのスコープで操作を制限できますが、所有者であるユーザーやサービスアカウントが持っていない権限を付与することはできません。スコープに制限のないキーでも、実行できる操作は所有者の実効権限の範囲内に限られます。
サービスアカウントにはワークロードに必要なロールだけを割り当て、そのうえで必要に応じてキーのスコープを制限してください。認可モデルについては権限とロールを参照してください。ID を作成してカスタムロールを割り当て、スコープを指定したキーを発行する設定例は、Terraform によるサービスアカウントの管理を参照してください。
管理 API キーとプロジェクトのワークロード用キーは用途が異なります。管理用の認証情報は、リソースのプロビジョニングと管理を行う信頼できるサービスで保管してください。アプリケーションからモデルにリクエストを送信するときは、そのプロジェクトのサービスアカウントの認証情報を使います。
プロジェクトとキーの管理の自動化
顧客向けにプロジェクトをプロビジョニングするアプリケーションでは、プロジェクトのサービスアカウントを使うことで、プロビジョニング処理を実行する開発者に依存しない ID を各ワークロードに割り当てられます。プロビジョニングサービスは管理 API を使ってプロジェクトとそのサービスアカウントを管理します。プロビジョニングされたアプリケーションは、自身のプロジェクト用認証情報を使います。
この用途に使う管理操作は次のとおりです。
| 操作 | 目的 |
|---|---|
| プロジェクトの作成 | ワークロードのリソースとサービスアカウントが属するプロジェクトを作成します。 |
| サービスアカウントの作成 | そのプロジェクト内にワークロードの ID を作成します。create_service_account_only オプションを使うと、デフォルトのロールを割り当てず、初期 API キーも発行せずにサービスアカウントを作成できます。 |
| サービスアカウントの API キーの作成 | 既存のサービスアカウントにキーを発行します。必要に応じて、キーのスコープや有効期限を設定できます。 |
| プロジェクト API キーの管理 | サービスアカウントのキーを含む既存のプロジェクトキーを一覧表示、取得、更新、または失効させることができます。 |
プロジェクト API キーの管理エンドポイントでは、別のユーザーに代わって、そのユーザーが所有するプロジェクトキーを作成することはできません。プログラムからキーを作成するには、サービスアカウントと、そのアカウント用のキー作成エンドポイントを使ってください。
デフォルトのロールを割り当てずにサービスアカウントを作成しただけでは、モデルにリクエストを送信する権限は付与されません。その認証情報を使う前に、必要な権限を割り当ててください。キーの作成時には組織とプロジェクトのキーポリシーも適用されます。サービスアカウントを使っても、これらのポリシーを回避することはできません。
認証情報のライフサイクル管理
API がサービスアカウントのキーの値をすべて返すのは、キーを作成したときだけです。キーはシークレットマネージャーに保存し、サーバー上でワークロードに渡してください。ブラウザーで実行するコード、モバイルアプリ、ソース管理、ログ、顧客に返すレスポンスには秘密のキーを含めないでください。
組織とプロジェクトのポリシーに従って有効期限を設定してください。キーをローテーションするには、新しいキーを発行し、ワークロードが新しいキーを使うように更新します。正常に動作することを確認してから、以前のキーを失効させてください。キーを切り替えても、同じサービスアカウントの ID を引き続き使えます。
ワークロードの役割が変わったときはアクセス権を見直し、ワークロードを廃止するときは認証情報を失効させてください。キーの管理と有効期限のポリシーについては本番環境での API キーのガイドラインを、API キーを保存せずに認証する方法についてはワークロード ID フェデレーションを参照してください。