Entra ID Graph API Permission Validator
いつこのスキルを使うか
以下のいずれかに該当する場合、作業開始前にこのスキルの内容を確認すること:
- •Graph APIの権限（スコープ/ロール）のGUIDをファイルに書こうとしている
- •
requiredResourceAccessを含むJSON/YAML/Bicep/Terraformを編集しようとしている - •admin consentの設定・実行・トラブルシュートをしている
- •
AADSTS650051やAADSTS系のエラーを調査している - •Entra IDアプリのマニフェストを編集している
- •新しいプロジェクトでMicrosoft Graph連携を設定している
プロジェクトやファイル形式は問わない。 deploy.yml、Bicep、Terraform、ARM Template、手書きのJSON、どれでも同じルールが適用される。
事故の教訓（2026-02）
deploy.ymlに書かれたGraph APIスコープのGUIDが8つ中6つ間違っていた。さらにClaudeがコメント（スコープ名）を追記した際もGUIDの正しさを検証せず、間違ったGUIDに間違ったコメントを付けた。コメント付きコードを「正しい」と信じて調査したため、原因特定に10時間以上を要した。
根本原則: GUIDは人間が読めない。コメントは検証の証拠ではない。唯一の検証方法はaz ad sp showの実行。
このスキルが行うこと
- •Graph APIスコープGUIDの正しさを検証する
- •deploy.ymlのpermissions.json編集時のガイドを提供する
- •Admin consent手順をガイドする
GUID検証（最重要）
Delegated Scope（type: "Scope"）の検証
bash
az ad sp show \
--id 00000003-0000-0000-c000-000000000000 \
--query "oauth2PermissionScopes[?value=='Files.Read.All'].{id:id,value:value}" \
-o json
Application Role（type: "Role"）の検証
bash
az ad sp show \
--id 00000003-0000-0000-c000-000000000000 \
--query "appRoles[?value=='Sites.Selected'].{id:id,value:value}" \
-o json
一括検証スクリプト
bash
# 引数でファイルを指定して検証 bash ~/.claude/skills/entra-graph-permissions/scripts/validate-graph-permissions.sh /path/to/deploy.yml # カレントディレクトリの .github/workflows/deploy.yml を自動検出 cd ~/PrivateMiner && bash ~/.claude/skills/entra-graph-permissions/scripts/validate-graph-permissions.sh
必須ワークフロー
permissions.jsonを編集する場合
- •書く前に: 追加したいスコープ名で
az ad sp showを実行し、正しいGUIDを取得する - •書いた後に:
validate-graph-permissions.shを実行して全GUIDを検証する - •コメントを付ける場合: コメント内容を
az ad sp showの出力と照合する
admin consentを実施する場合
ステップ1: Delegated Permissionsのconsent
管理者アカウントでconsent URLにアクセス:
code
https://private-miner-dev.azurewebsites.net/auth/login?admin_consent=1
ステップ2: Sites.Selected（Application Role）のサイト単位権限付与
SlidePro機能で使用するSites.Selectedはapplication roleのため、admin consent後にさらにサイト単位の権限付与が必要。
consent状態の確認
bash
# サービスプリンシパルの確認
az ad sp list --filter "displayName eq 'Private Miner (dev)'" \
--query "[0].{id:id,appId:appId}" -o json
# Permission Grantsの確認
SP_ID=$(az ad sp list --filter "displayName eq 'Private Miner (dev)'" --query "[0].id" -o tsv)
az rest --method GET --url "https://graph.microsoft.com/v1.0/servicePrincipals/$SP_ID/oauth2PermissionGrants"
admin consentが失敗する場合の調査手順
- •まずGUIDを疑う — コメントが付いていても信用しない
- •
validate-graph-permissions.shを実行 - •全GUIDがPASSしたら、次にconsent手順・テナント設定を調査
「コードは正しいが手順が悪い」と結論づける前に、必ずGUIDの検証を完了すること。
正しいGUID一覧（2026年2月時点）
| スコープ名 | GUID | 種類 |
|---|---|---|
| User.Read | e1fe6dd8-ba31-4d61-89e7-88639da4683d | Scope |
| Files.Read.All | df85f4d6-205c-4ac5-a5ea-6bf408dba283 | Scope |
| Files.ReadWrite.All | 863451e7-0667-486c-a5d6-d135439485f0 | Scope |
| Sites.Read.All | 205e70e5-aba6-4c52-a976-6d2d46c48043 | Scope |
| GroupMember.Read.All | bc024368-1153-4739-b217-4326f2e966d0 | Scope |
| Team.ReadBasic.All | 485be79e-c497-4b35-9400-0e3fa7f2a5d4 | Scope |
| Channel.ReadBasic.All | 9d8982ae-4365-4f57-95e9-d6032a4c0b87 | Scope |
| ChannelMessage.Send | ebf0f66e-9fb1-49e4-a278-222f76911cf4 | Scope |
| Sites.Selected | 883ea226-0bf2-4a8f-9f9d-92c9162a727d | Role |
注意: このテーブルも古くなる可能性がある。必ずaz ad sp showで検証すること。
.defaultスコープのadmin consentの挙動
scope=https://graph.microsoft.com/.defaultでadmin consentすると、requiredResourceAccessに登録された全スコープをまとめてconsentしようとする。1つでも無効なGUIDがあると、consent全体がAADSTS650051エラーで拒否される（全か無か）。
よくあるミス
| ミス | 結果 |
|---|---|
| GUIDのコピペでズレた | 別のスコープを指すか、存在しないGUIDになる |
| delegated scope用のGUIDをtype:"Role"で登録 | consent時にエラー |
| application role用のGUIDをtype:"Scope"で登録 | consent時にエラー |
| コメントのスコープ名を信用して検証しなかった | 間違いに気づかない |
関連ドキュメント
- •Private Miner CLAUDE.md: ルール7「GUIDは必ず実機検証する」
- •Obsidianノート:
2026-02-04_Graph APIスコープGUIDの罠とadmin consentが失敗する原因.md - •検証スクリプト:
~/PrivateMiner/scripts/validate-graph-permissions.sh