GCP プロジェクトと OAuth の構造

ひとことで

プロジェクトの中には何が入っているのか

Google Cloud の「プロジェクト」は、課金と権限をまとめる入れ物でしかない。中身は大きく 3 種類に分かれていて、この 3 つが混同されやすい。

ID と番号は別物

プロジェクトには ID（nzw-ai-agent のような文字列）と 番号（331995618405 のような数字）の 2 つの呼び名がある。同じものを指すが、出てくる場所が違う。

• 番号は OAuth クライアント ID の先頭に必ず埋め込まれている。331995618405-no02rqsd….apps.googleusercontent.com の前半がそれ
• ID はサービスアカウントのアドレス …@nzw-ai-agent.iam.gserviceaccount.com や、コンソールの URL に出る

つまりクライアント ID を見れば、それがどのプロジェクトのものか一目で分かる。逆にサービスアカウントの鍵ファイルには番号が入っていないので、両者が同じプロジェクトかどうかは鍵だけでは判断できない。

「API を有効にする」は、権限を配ることではない

ここが最初に引っかかったところ。API の有効化は、そのプロジェクトからその API を呼べる状態にするだけで、誰かがアクセスできるようになるわけではない。蛇口を付けただけで、水を出す権利は別に配る必要がある。

だから Gmail API を有効にしても、AI ワークスペースのログインには何の影響もない。ワークスペースのログインは Gmail API を呼んでいないので、蛇口が増えたことにすら気づかない。

OAuth クライアント ID は「アプリの身分証」

クライアント ID はアプリ 1 つにつき 1 枚の身分証で、いくつでも発行できる。重要なのは種別によって使える認証の流れが違うこと。同じプロジェクトの中に用途別に何枚あっても構わないし、互いに干渉しない。

Gmail のトークンを取るのにウェブ用ではなくデスクトップ用を新規に作ったのは、この 「戻り先」の違いが理由。トークン取得スクリプトは手元でローカルサーバーを立てて http://localhost で認可コードを受け取るので、ウェブ用クライアントでは受け取れない。

スコープが、同意画面に何が出るかを決める

「何を許可するのか」を決めているのは API でもクライアントでもなくスコープ。そして同意画面に表示されるのは、そのとき要求されたスコープだけ。プロジェクトに登録されている他のスコープは出てこない。

AI ワークスペースのログインは google.accounts.id という ID トークン専用の仕組みを使っていて、そもそもスコープを一切要求しない。返ってくるのは「この人は誰か」を示す署名付きの JWT だけ。だから制限付きスコープを別のクライアントが要求しても、ワークスペース側の同意画面は変わりようがない。

権限は、コードの 1 行が決めている

ここが一番の勘所。「何を許可してもらうか」を決めているのはコンソールの設定ではなく、コード側で書いたスコープの文字列。コンソールでの登録は審査のための申告であって、実際の要求内容はアプリが認可のたびに送っている。

1. スコープを宣言する

Gmail 監視では、この 1 行がすべての起点になっている。

SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]

gmail.readonly は読み取り専用を意味する。送信したいなら gmail.send、削除まで許すなら gmail.modify と、別の文字列を書く。つまり権限の強さは URL の末尾で決まる。ここを gmail.modify に書き換えれば、それだけでメールを消せる権限を要求するアプリになってしまう。逆に言えば、書かない権限は絶対に付かない。

2. その宣言を持って認可を求めに行く

スクリプトはこの SCOPES を渡してブラウザを開く。ユーザーが見る同意画面の中身は、ここで渡した配列そのもの。

flow = InstalledAppFlow.from_client_config(
    {"installed": {"client_id": client_id, "client_secret": client_secret, ...}},
    SCOPES,          # ← 同意画面に出るのはこれ
)

creds = flow.run_local_server(
    port=0,
    access_type="offline",        # refresh token を貰う（長期間使うため）
    prompt="consent select_account",
)

access_type="offline" が「アプリを閉じた後も使い続けたい」という意思表示で、これがあると refresh token が返る。付けないとその場限りのアクセストークンしか貰えず、定期実行できない。

3. 貰ったトークンで API を呼ぶ

ここから先はブラウザも同意画面も出てこない。サーバーが持っている refresh token だけで動く。

credentials = Credentials(
    token=None,
    refresh_token=refresh_token,   # 手順 2 で貰った長期トークン
    token_uri="https://oauth2.googleapis.com/token",
    client_id=client_id,
    client_secret=client_secret,
    scopes=GMAIL_SCOPES,
)

注意したいのは、ここに書いた scopes が権限を増やすわけではないということ。権限が確定したのは手順 2 の同意の瞬間で、この行は「そのとき何を貰ったか」を控えているだけ。ここを gmail.modify に書き換えても、実際に許可されていなければ API 呼び出しが弾かれる。

比較：ワークスペースのログインは何も宣言していない

同じ理屈で読むと、AI ワークスペース側が Gmail の許可を求めない理由がはっきりする。

google.accounts.id.initialize({
  client_id: CLIENT_ID,
  callback: handleCredentialResponse,
  auto_select: false,
});

scope という項目がどこにもない。書き忘れではなく、google.accounts.id は本人確認専用の API で、スコープを指定するオプションが存在しない。API アクセスを求めたいときは google.accounts.oauth2 という別の名前空間を使う必要があり、こちらはサイト内で一度も使っていない。

だからワークスペースのログインで許可画面が出ることは、コードを書き換えない限り起こらない。Gmail API を有効化しようが、別のクライアントが制限付きスコープを要求しようが、この initialize の中身は変わらない。

受け取った側の検証

サーバーは送られてきた ID トークンを Google の公開鍵で検証する。audience は「このトークンは本当にうちのクライアント宛か」の確認。

id_info = google.oauth2.id_token.verify_oauth2_token(
    id_token, request_adapter, audience=settings.GOOGLE_CLIENT_ID
)

ここで使う GOOGLE_CLIENT_ID はウェブ用クライアントの ID。Gmail 監視で使うデスクトップ用クライアントとは別物なので、設定も GMAIL_OAUTH_CLIENT_ID という別の変数に分けてある。1 つの変数に 2 つの役目を持たせると、Gmail 側を直したときにログインの検証対象がずれて壊れる。

唯一の共有物 — 同意画面

ここまで「独立している」と繰り返してきたが、1 つだけプロジェクト全体で共有されるものがある。それが OAuth 同意画面で、クライアントを何枚作っても同意画面は 1 枚しかない。

同意画面が持っている設定のうち、影響が大きいのは公開ステータス（テスト中／本番）。これはプロジェクト単位なので、片方のクライアントのために切り替えると、もう片方も同じ状態になる。

公開ステータスごとの上限・トークン寿命・警告画面の有無、および審査を通すまでの実務は、別ノートに詳しく書いた。とくに「テスト中」のままだと認可が 7 日で失効する点は、常時動かすバックグラウンド処理には致命的なので、そちらを読んでおくとよい。

今回の判断

Gmail 用に新しいクライアントを立てた

DECISION　既存のウェブクライアントを使い回さず、デスクトップ種別を 1 枚追加した。設定も GOOGLE_CLIENT_ID とは別の GMAIL_OAUTH_CLIENT_ID に分離した。

WHY　技術的には http://localhost に戻せないという制約が理由。ただしそれ以上に、ウェブクライアントの ID はログインの本人確認（audience 検証）に使っている値で、ここを Gmail 用に書き換えると認証の検証対象がずれる。1 つの値に 2 つの役目を持たせると、片方を直すともう片方が壊れる。

RESULT　用途ごとに独立した。Gmail 側のクライアントを作り直しても、ログインには影響しない。

プロジェクトは分けず、既存のものに相乗りした

DECISION　Gmail 監視専用の新規プロジェクトは作らず、AI ワークスペースと同じ 331995618405 に同居させた。

WHY　当初は「認証まわりを触りたくないから分けるべきか」と考えた。だが影響範囲を洗った結果、共有物は同意画面 1 枚だけで、ワークスペース側は基本スコープしか使っておらず、公開ステータスを変えても実際に使える人は変わらない（アプリ側の許可リストが効く）ことが確認できた。分ける理由が消えた。

RESULT　管理対象のプロジェクトが増えずに済んだ。ただしこの判断は「ワークスペースが基本スコープしか使っていない」という前提に依存している。将来ワークスペースが機微・制限付きスコープを要求するようになったら、前提が崩れるので分離を再検討する。

迷ったときの early return

結論としては、同意画面に触るとき以外は、そんなに怖がらなくていい。逆に同意画面を触るときは、そのプロジェクトにぶら下がっている全アプリを思い出してから手を動かす。