entra-agent-user

SKILL: Microsoft Entra Agent ID でのエージェントユーザーの作成

概要

エージェントユーザーとは、Microsoft Entra ID における特殊なユーザー ID であり、AI エージェントがデジタルワーカーとして動作できるようにするものです。これにより、エージェントはユーザー ID を厳密に必要とする API やサービス（例: Exchange メールボックス、Teams、組織図）にアクセスしつつ、適切なセキュリティ境界を維持できます。

エージェントユーザーは idtyp=user のトークンを受け取ります。これは idtyp=app を受け取る通常のエージェント ID とは異なります。

---

前提条件

• Agent ID 機能を備えた Microsoft Entra テナント
• エージェント ID ブループリントから作成された エージェント ID（種類が ServiceIdentity のサービスプリンシパル）
• 次のいずれかのアクセス許可:
  • AgentIdUser.ReadWrite.IdentityParentedBy（最小特権）
  • AgentIdUser.ReadWrite.All
  • User.ReadWrite.All
• 呼び出し元は、少なくとも Agent ID 管理者ロールを持っている必要があります（委任されたシナリオの場合）

重要: identityParentId は、真のエージェント ID（エージェント ID ブループリントから作成されたもの）を参照する必要があり、通常のアプリケーションサービスプリンシパルを参照してはいけません。サービスプリンシパルに @odata.type: #microsoft.graph.agentIdentity と servicePrincipalType: ServiceIdentity があるかを確認することで検証できます。

---

アーキテクチャ

Agent Identity Blueprint (application template)
    │
    ├── Agent Identity (service principal - ServiceIdentity)
    │       │
    │       └── Agent User (user - agentUser) ← 1:1 relationship
    │
    └── Agent Identity Blueprint Principal (service principal in tenant)

コンポーネント	種類	トークン要求	目的
エージェント ID	サービスプリンシパル	idtyp=app	バックエンド/API 操作
エージェントユーザー	ユーザー (agentUser)	idtyp=user	M365 でデジタルワーカーとして動作

---

ステップ 1: エージェント ID が存在することを確認する

エージェントユーザーを作成する前に、エージェント ID が適切な agentIdentity 型であることを確認します:

GET https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-id}
Authorization: Bearer <token>

応答に次の内容が含まれていることを確認します:

{
  "@odata.type": "#microsoft.graph.agentIdentity",
  "servicePrincipalType": "ServiceIdentity",
  "agentIdentityBlueprintId": "<blueprint-id>"
}

PowerShell

Connect-MgGraph -Scopes "Application.Read.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome
Invoke-MgGraphRequest -Method GET `
  -Uri "https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-id>" | ConvertTo-Json -Depth 3

よくある間違い: アプリ登録の appId や通常のアプリケーションサービスプリンシパルの id を使用すると失敗します。ブループリントから作成されたエージェント ID のみが機能します。

---

ステップ 2: エージェントユーザーを作成する

HTTP リクエスト

POST https://graph.microsoft.com/beta/users/microsoft.graph.agentUser
Content-Type: application/json
Authorization: Bearer <token>

{
  "accountEnabled": true,
  "displayName": "My Agent User",
  "mailNickname": "my-agent-user",
  "userPrincipalName": "[email protected]",
  "identityParentId": "<agent-identity-object-id>"
}

必須プロパティ

プロパティ	種類	説明
accountEnabled	Boolean	アカウントを有効にするには true
displayName	String	人間が読みやすい名前
mailNickname	String	メールエイリアス（スペースや特殊文字は不可）
userPrincipalName	String	UPN — テナント内で一意である必要があります（alias@verified-domain）
identityParentId	String	親エージェント ID のオブジェクト ID

PowerShell

Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome

$body = @{
  accountEnabled    = $true
  displayName       = "My Agent User"
  mailNickname      = "my-agent-user"
  userPrincipalName = "[email protected]"
  identityParentId  = "<agent-identity-object-id>"
} | ConvertTo-Json

Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/microsoft.graph.agentUser" `
  -Body $body -ContentType "application/json" | ConvertTo-Json -Depth 3

重要な注意点

• パスワードなし — エージェントユーザーはパスワードを持てません。親エージェント ID の資格情報を介して認証します。
• 1:1 の関係 — 各エージェント ID は最大 1 つのエージェントユーザーを持てます。2 つ目を作成しようとすると 400 Bad Request が返されます。
• userPrincipalName は一意である必要があります。既存ユーザーの UPN を再利用しないでください。

---

ステップ 3: マネージャーを割り当てる（任意）

マネージャーを割り当てると、エージェントユーザーが組織図（例: Teams）に表示されるようになります。

PUT https://graph.microsoft.com/beta/users/{agent-user-id}/manager/$ref
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.id": "https://graph.microsoft.com/beta/users/{manager-user-id}"
}

PowerShell

$managerBody = '{"@odata.id":"https://graph.microsoft.com/beta/users/<manager-user-id>"}'
Invoke-MgGraphRequest -Method PUT `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/manager/`$ref" `
  -Body $managerBody -ContentType "application/json"

---

ステップ 4: 使用場所を設定し、ライセンスを割り当てる（任意）

エージェントユーザーがメールボックスや Teams のプレゼンスなどを持つには、ライセンスが必要です。使用場所を先に設定する必要があります。

使用場所を設定する

PATCH https://graph.microsoft.com/beta/users/{agent-user-id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "usageLocation": "US"
}

利用可能なライセンスを一覧表示する

GET https://graph.microsoft.com/beta/subscribedSkus?$select=skuPartNumber,skuId,consumedUnits,prepaidUnits
Authorization: Bearer <token>

Organization.Read.All アクセス許可が必要です。

ライセンスを割り当てる

POST https://graph.microsoft.com/beta/users/{agent-user-id}/assignLicense
Content-Type: application/json
Authorization: Bearer <token>

{
  "addLicenses": [
    { "skuId": "<sku-id>" }
  ],
  "removeLicenses": []
}

PowerShell（まとめて実行）

Connect-MgGraph -Scopes "User.ReadWrite.All","Organization.Read.All" -TenantId "<tenant>" -NoWelcome

# Set usage location
Invoke-MgGraphRequest -Method PATCH `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>" `
  -Body '{"usageLocation":"US"}' -ContentType "application/json"

# Assign license
$licenseBody = '{"addLicenses":[{"skuId":"<sku-id>"}],"removeLicenses":[]}'
Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/assignLicense" `
  -Body $licenseBody -ContentType "application/json"

ヒント: Entra 管理センターの [ID] → [ユーザー] → [すべてのユーザー] → エージェントユーザーを選択 → [ライセンスとアプリ] からライセンスを割り当てることもできます。

---

プロビジョニング時間

サービス	推定時間
Exchange メールボックス	5～30 分
Teams の可用性	15 分～24 時間
組織図 / ユーザー検索	最大 24～48 時間
SharePoint / OneDrive	5～30 分
グローバルアドレス一覧	最大 24 時間

---

エージェントユーザーの機能

• ✅ Microsoft Entra グループに追加される（動的グループを含む）
• ✅ ユーザー専用 API（idtyp=user トークン）にアクセスする
• ✅ メールボックス、予定表、連絡先を所有する
• ✅ Teams のチャットおよびチャネルに参加する
• ✅ 組織図および People 検索に表示される
• ✅ 管理単位に追加される
• ✅ ライセンスが割り当てられる

エージェントユーザーのセキュリティ制約

• ❌ パスワード、パスキー、対話型サインインを持つことができない
• ❌ 特権管理者ロールを割り当てることができない
• ❌ ロール割り当て可能なグループに追加することができない
• ❌ 既定ではゲストユーザーと同様のアクセス許可
• ❌ カスタムロールの割り当ては利用できない

---

トラブルシューティング

エラー	原因	修正
Agent user IdentityParent does not exist	identityParentId が存在しないオブジェクト、またはエージェント ID 以外のオブジェクトを指している	その ID が通常のアプリではなく agentIdentity サービスプリンシパルであることを確認してください
400 Bad Request（identityParentId がすでにリンクされている）	エージェント ID にすでにエージェントユーザーが存在する	各エージェント ID がサポートするエージェントユーザーは 1 つだけです
UPN での 409 Conflict	userPrincipalName がすでに使用されている	一意の UPN を使用してください
ライセンスの割り当てが失敗する	使用場所が設定されていない	ライセンスを割り当てる前に usageLocation を設定してください

---

参考資料

• エージェント ID
• エージェントユーザー
• エージェントサービスプリンシパル
• エージェント ID ブループリントの作成
• エージェント ID の作成
• agentUser リソースの種類（Graph API）
• agentUser の作成（Graph API）