# entra-graph-permissions

> Microsoft Graph APIのスコープGUID、Entra ID (Azure AD) アプリ登録、requiredResourceAccess、 admin consent、oauth2PermissionScopes、appRoles に関わる作業時に**必ず**使用すること。 具体的には: Graph APIの権限をコードに書く時、GUIDをコピペする時、admin consentが失敗した時、 AADSTS650051エラーが出た時、Entra IDアプリのマニフェストを編集する時、 新しいプロジェクトでGraph API権限を設定する時。 GUIDのコピペミスによる10時間のデバッグ事故（2026-02）の再発を防止する。 **重要: Graph APIのGUIDをファイルに書く前に、必ずこのスキルを参照すること。**

- Author: Masahiko Ebisuda
- Repository: ebibibi/ebibibi-claude-settings
- Version: 20260205144814
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ebibibi/ebibibi-claude-settings
- Web: https://mule.run/skillshub/@@ebibibi/ebibibi-claude-settings~entra-graph-permissions:20260205144814

---

---
name: entra-graph-permissions
description: >-
  Microsoft Graph APIのスコープGUID、Entra ID (Azure AD) アプリ登録、requiredResourceAccess、
  admin consent、oauth2PermissionScopes、appRoles に関わる作業時に**必ず**使用すること。
  具体的には: Graph APIの権限をコードに書く時、GUIDをコピペする時、admin consentが失敗した時、
  AADSTS650051エラーが出た時、Entra IDアプリのマニフェストを編集する時、
  新しいプロジェクトでGraph API権限を設定する時。
  GUIDのコピペミスによる10時間のデバッグ事故（2026-02）の再発を防止する。
  **重要: Graph APIのGUIDをファイルに書く前に、必ずこのスキルを参照すること。**
allowed-tools: Bash(bash *)
---

# 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を編集する場合

1. **書く前に**: 追加したいスコープ名で`az ad sp show`を実行し、正しいGUIDを取得する
2. **書いた後に**: `validate-graph-permissions.sh`を実行して全GUIDを検証する
3. **コメントを付ける場合**: コメント内容を`az ad sp show`の出力と照合する

### admin consentを実施する場合

#### ステップ1: Delegated Permissionsのconsent

管理者アカウントでconsent URLにアクセス:
```
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が失敗する場合の調査手順

1. **まずGUIDを疑う** — コメントが付いていても信用しない
2. `validate-graph-permissions.sh`を実行
3. 全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`