Google Workspace の Domain-Wide Delegation で「今どのスコープが許可されているか」を管理画面を見ずに実測する

何に使うか

• サービスアカウント（SA）に DWD でスコープを足したいが、管理コンソールの既存設定を見られない（自分は管理者でない／スクショ往復を避けたい）。
• 「上書き」で既存スコープを消さないよう、既存スコープ＋追加分の完全な値を管理者に渡したい。
• 管理者が設定した後に「反映されたか」を自動で検知したい（反映は最大24時間かかることがある）。

原理

DWD のトークン交換（JWT Bearer）は、要求したスコープが全部許可リストに含まれる時だけ成功し、1つでも欠けると 401 unauthorized_client を返す。 → スコープを1つずつ単独で要求すれば、各スコープの許可有無が確定できる。API 呼び出しは一切行わずトークン発行だけなので副作用はない。

手順（Node 18+、依存なし）

1. SA の JSON 鍵（client_email, private_key, client_id）と、なりすます Workspace ユーザー（sub）を用意する。鍵の値はログに出さない。
2. 調べたいスコープの候補を列挙する（よく使うもの: gmail.send / gmail.readonly / gmail.modify / gmail.compose / gmail.metadata / gmail.settings.basic / spreadsheets / spreadsheets.readonly / drive / drive.readonly / drive.file / calendar / calendar.readonly / admin.directory.user.readonly / https://mail.google.com/）。
3. 各スコープについて下のスクリプトで 1 回ずつトークン取得を試す。

// dwd-probe.mjs  usage: SA_KEY_PATH=key.json SUBJECT=user@<自社ドメイン> node dwd-probe.mjs
import fs from 'node:fs';
import crypto from 'node:crypto';
const key = JSON.parse(fs.readFileSync(process.env.SA_KEY_PATH, 'utf8'));
const subject = process.env.SUBJECT;
const scopes = ['gmail.send', 'gmail.readonly', 'spreadsheets.readonly' /* … */]
  .map((s) => (s.startsWith('https://') ? s : `https://www.googleapis.com/auth/${s}`));
console.log('client_id', key.client_id);
for (const scope of scopes) {
  const now = Math.floor(Date.now() / 1000);
  const enc = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');
  const unsigned = `${enc({ alg: 'RS256', typ: 'JWT' })}.${enc({
    iss: key.client_email, sub: subject, scope,
    aud: 'https://oauth2.googleapis.com/token', iat: now, exp: now + 300,
  })}`;
  const sig = crypto.createSign('RSA-SHA256').update(unsigned).sign(key.private_key).toString('base64url');
  const r = await fetch('https://oauth2.googleapis.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion: `${unsigned}.${sig}` }),
  });
  const j = await r.json();
  console.log(scope.split('/').pop(), '→', r.status, j.access_token ? 'OK' : `${j.error}`); // トークン本体は出さない
}

4. OK だったスコープ＝現在の許可リスト（候補に挙げた範囲での実測）。これに追加分を足したカンマ区切りの完全な値を作り、管理者に「該当 Client ID の行を編集 → OAuth スコープ欄を丸ごとこの値に置換 → 承認」と渡す。
5. 反映待ちは同じスクリプトをループ（例: 5分おき・最長24時間）で回し、追加スコープが OK になった時点で次の処理（初回取込など）へ進む。

注意点

• 候補に無いスコープは検出できない。**未許可と出たものは「候補の中では未許可」**であって、全スコープの一覧ではない。重要な既存連携がある場合は候補を広めに取る。
• sub 無し（なりすましなし）でのトークン取得は DWD を通らないので、この判定には使えない。
• 管理コンソールの「新しく追加」で同じ Client ID を登録すると既存行を上書きしうる。既存行の「編集」を使うよう案内する。
• DWD のスコープを変更する公開 API は無い（Google 公式ヘルプも管理コンソールの手順のみ）。変更そのものは特権管理者の操作になる。
• アプリ側では、DWD で許可されていないスコープを1つでも JWT に混ぜると全リクエストが失敗する。用途別（送信用・読取用）にトークンのキャッシュを分け、許可済みスコープだけを要求する。