entra-agent-user

技能：在 Microsoft Entra 代理身分識別中建立代理使用者

概觀

代理使用者是 Microsoft Entra ID 中的一種特殊使用者身分，讓 AI 代理程式能作為數位工作者運作。它允許代理程式存取嚴格要求使用者身分的 API 和服務（例如 Exchange 信箱、Teams、組織圖），同時維持適當的安全性邊界。

代理使用者取得的權杖包含 idtyp=user，而一般代理身分取得的權杖則為 idtyp=app。

必要條件

具備代理身分識別功能的 Microsoft Entra 租用戶
從代理身分藍圖建立的代理身分（類型為 ServiceIdentity 的服務主體）
下列其中一項權限：
- AgentIdUser.ReadWrite.IdentityParentedBy（最低權限）
- AgentIdUser.ReadWrite.All
- User.ReadWrite.All
呼叫者至少必須具備代理身分識別管理員角色（在委派案例中）

重要： identityParentId 必須參照真正的代理身分（透過代理身分藍圖建立），而非一般的應用程式服務主體。您可以檢查服務主體是否具有 @odata.type: #microsoft.graph.agentIdentity 和 servicePrincipalType: ServiceIdentity 來驗證。

架構

代理身分藍圖（應用程式範本）
    │
    ├── 代理身分（服務主體 - ServiceIdentity）
    │       │
    │       └── 代理使用者（使用者 - agentUser）← 1:1 關係
    │
    └── 代理身分藍圖主體（租用戶中的服務主體）

元件	類型	權杖宣告	用途
代理身分	服務主體	`idtyp=app`	後端/API 操作
代理使用者	使用者 (`agentUser`)	`idtyp=user`	在 M365 中作為數位工作者

步驟 1：確認代理身分存在

在建立代理使用者之前，請確認代理身分是正確的 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 將會失敗。只有從藍圖建立的代理身分才能運作。

步驟 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": "my-agent-user@yourtenant.onmicrosoft.com",
  "identityParentId": "<agent-identity-object-id>"
}

必要屬性

屬性	類型	說明
`accountEnabled`	布林值	`true` 以啟用帳戶
`displayName`	字串	易記名稱
`mailNickname`	字串	郵件別名（無空格/特殊字元）
`userPrincipalName`	字串	UPN — 必須在租用戶中唯一（`alias@verified-domain`）
`identityParentId`	字串	父代理身分的物件識別碼

PowerShell

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

$body = @{
  accountEnabled    = $true
  displayName       = "My Agent User"
  mailNickname      = "my-agent-user"
  userPrincipalName = "my-agent-user@yourtenant.onmicrosoft.com"
  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

重點說明

無密碼 — 代理使用者不能有密碼。他們透過父代理身分的憑證進行驗證。
1:1 關係 — 每個代理身分最多只能有一個代理使用者。嘗試建立第二個會回傳 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

# 設定使用位置
Invoke-MgGraphRequest -Method PATCH `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>" `
  -Body '{"usageLocation":"US"}' -ContentType "application/json"

# 指派授權
$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 系統管理中心，在身分識別 → 使用者 → 所有使用者 → 選取代理使用者 → 授權與應用程式來指派授權。

佈建時間

服務	預估時間
Exchange 信箱	5–30 分鐘
Teams 可用性	15 分鐘 – 24 小時
組織圖 / 人員搜尋	最多 24–48 小時
SharePoint / OneDrive	5–30 分鐘
全域通訊清單	最多 24 小時

代理使用者功能

✅ 可加入 Microsoft Entra 群組（包括動態群組）
✅ 可存取僅限使用者的 API（idtyp=user 權杖）
✅ 擁有信箱、行事曆和連絡人
✅ 可參與 Teams 聊天和頻道
✅ 出現在組織圖和人員搜尋中
✅ 可加入系統管理單位
✅ 可指派授權

代理使用者安全性限制

❌ 不能有密碼、通行金鑰或互動式登入
❌ 不能指派特殊權限管理員角色
❌ 不能加入可指派角色的群組
❌ 預設權限類似於來賓使用者
❌ 無法指派自訂角色

疑難排解

錯誤	原因	修正
`Agent user IdentityParent does not exist`	`identityParentId` 指向不存在或非代理身分的物件	確認該識別碼是 `agentIdentity` 服務主體，而非一般應用程式
`400 Bad Request`（identityParentId 已連結）	該代理身分已有一個代理使用者	每個代理身分僅支援一個代理使用者
`409 Conflict`（UPN 衝突）	`userPrincipalName` 已被使用	使用唯一的 UPN
授權指派失敗	未設定使用位置	在指派授權前先設定 `usageLocation`

參考資料

您可能也喜歡

golang-security

2.3Ksecurity

Golang 的安全最佳實務與漏洞防範。涵蓋注入（SQL、命令、XSS）、密碼學、檔案系統安全、網路安全、Cookie、機密管理、記憶體安全與日誌記錄。適用於撰寫、審查或稽核 Go 程式碼的安全性，或處理任何涉及密碼學、I/O、機密管理、使用者輸入處理或身分驗證的高風險程式碼。包含安全工具的設定。

samber

獲取

security-and-hardening

77Ksecurity

強化程式碼以抵禦漏洞。在處理使用者輸入、驗證、資料儲存或外部整合時使用。在建立任何接受不受信任資料、管理使用者工作階段或與第三方服務互動的功能時使用。

addyosmani

獲取

api-security-best-practices

43Ksecurity

Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities

sickn33

獲取

繼續探索

瀏覽 security 熱門 Skills 最近更新

entra-agent-user

相關技能

技能：在 Microsoft Entra 代理身分識別中建立代理使用者

概觀

必要條件

架構

步驟 1：確認代理身分存在

PowerShell

步驟 2：建立代理使用者

HTTP 請求

必要屬性

PowerShell

重點說明

步驟 3：指派主管（選擇性）

PowerShell

步驟 4：設定使用位置並指派授權（選擇性）

設定使用位置

列出可用授權

指派授權

PowerShell（一次完成）

佈建時間

代理使用者功能

代理使用者安全性限制

疑難排解

參考資料

您可能也喜歡

golang-security

security-and-hardening

api-security-best-practices

繼續探索