entra-agent-user by github/awesome-copilot
npx skills add https://github.com/github/awesome-copilot --skill entra-agent-user代理用户 是 Microsoft Entra ID 中的一种特殊用户身份,它使 AI 代理能够作为数字工作者运行。它允许代理访问那些严格要求用户身份(例如,Exchange 邮箱、Teams、组织架构图)的 API 和服务,同时保持适当的安全边界。
与接收 idtyp=app 令牌的常规代理身份不同,代理用户接收的令牌带有 idtyp=user 声明。
ServiceIdentity 的服务主体)AgentIdUser.ReadWrite.IdentityParentedBy(最低特权)AgentIdUser.ReadWrite.AllUser.ReadWrite.All广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
重要提示:
identityParentId必须引用一个真正的代理身份(通过代理身份蓝图创建),而不是一个普通的应用程序服务主体。您可以通过检查服务主体是否具有@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)
| 组件 | 类型 | 令牌声明 | 用途 |
|---|---|---|---|
| 代理身份 | 服务主体 | idtyp=app | 后端/API 操作 |
| 代理用户 | 用户 (agentUser) | idtyp=user | 在 M365 中作为数字工作者运行 |
在创建代理用户之前,请确认代理身份是适当的 agentIdentity 类型:
GET https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-id}
Authorization: Bearer <token>
验证响应包含:
{
"@odata.type": "#microsoft.graph.agentIdentity",
"servicePrincipalType": "ServiceIdentity",
"agentIdentityBlueprintId": "<blueprint-id>"
}
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将会失败。只有从蓝图创建的代理身份才有效。
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 | 字符串 | 父代理身份的对象 ID |
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
400 Bad Request。userPrincipalName 必须是唯一的。不要重复使用现有用户的 UPN。分配经理允许代理用户出现在组织架构图中(例如,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}"
}
$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"
代理用户需要许可证才能拥有邮箱、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": []
}
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 管理中心 分配许可证,路径为:身份 → 用户 → 所有用户 → 选择代理用户 → 许可证和应用。
| 服务 | 预计时间 |
|---|---|
| Exchange 邮箱 | 5–30 分钟 |
| Teams 可用性 | 15 分钟 – 24 小时 |
| 组织架构图 / 人员搜索 | 最长 24–48 小时 |
| SharePoint / OneDrive | 5–30 分钟 |
| 全局地址列表 | 最长 24 小时 |
idtyp=user 令牌)| 错误 | 原因 | 解决方法 |
|---|---|---|
Agent user IdentityParent does not exist | identityParentId 指向不存在的或非代理身份的对象 | 验证该 ID 是否为 agentIdentity 服务主体,而不是普通应用 |
400 Bad Request (identityParentId already linked) | 该代理身份已有一个代理用户 | 每个代理身份仅支持一个代理用户 |
409 Conflict on UPN | userPrincipalName 已被占用 | 使用唯一的 UPN |
| 许可证分配失败 | 未设置使用位置 | 在分配许可证之前设置 usageLocation |
每周安装量
7.3K
代码仓库
GitHub Stars
26.7K
首次出现
Feb 24, 2026
安全审计
安装于
codex7.2K
gemini-cli7.2K
opencode7.2K
cursor7.2K
github-copilot7.2K
amp7.1K
An agent user is a specialized user identity in Microsoft Entra ID that enables AI agents to act as digital workers. It allows agents to access APIs and services that strictly require user identities (e.g., Exchange mailboxes, Teams, org charts), while maintaining appropriate security boundaries.
Agent users receive tokens with idtyp=user, unlike regular agent identities which receive idtyp=app.
ServiceIdentity) created from an agent identity blueprintAgentIdUser.ReadWrite.IdentityParentedBy (least privileged)AgentIdUser.ReadWrite.AllUser.ReadWrite.AllImportant: The
identityParentIdmust reference a true agent identity (created via an agent identity blueprint), NOT a regular application service principal. You can verify by checking that the service principal has@odata.type: #microsoft.graph.agentIdentityandservicePrincipalType: 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)
| Component | Type | Token Claim | Purpose |
|---|---|---|---|
| Agent Identity | Service Principal | idtyp=app | Backend/API operations |
| Agent User | User (agentUser) | idtyp=user | Act as a digital worker in M365 |
Before creating an agent user, confirm the agent identity is a proper agentIdentity type:
GET https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-id}
Authorization: Bearer <token>
Verify the response contains:
{
"@odata.type": "#microsoft.graph.agentIdentity",
"servicePrincipalType": "ServiceIdentity",
"agentIdentityBlueprintId": "<blueprint-id>"
}
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
Common mistake: Using an app registration's
appIdor a regular application service principal'sidwill fail. Only agent identities created from blueprints work.
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>"
}
| Property | Type | Description |
|---|---|---|
accountEnabled | Boolean | true to enable the account |
displayName | String | Human-friendly name |
mailNickname | String | Mail alias (no spaces/special chars) |
userPrincipalName | String | UPN — must be unique in the tenant (alias@verified-domain) |
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
400 Bad Request.userPrincipalName must be unique. Don't reuse an existing user's UPN.Assigning a manager allows the agent user to appear in org charts (e.g., 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}"
}
$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"
A license is needed for the agent user to have a mailbox, Teams presence, etc. Usage location must be set first.
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>
Requires Organization.Read.All permission.
POST https://graph.microsoft.com/beta/users/{agent-user-id}/assignLicense
Content-Type: application/json
Authorization: Bearer <token>
{
"addLicenses": [
{ "skuId": "<sku-id>" }
],
"removeLicenses": []
}
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"
Tip: You can also assign licenses via the Entra admin center under Identity → Users → All users → select the agent user → Licenses and apps.
| Service | Estimated Time |
|---|---|
| Exchange mailbox | 5–30 minutes |
| Teams availability | 15 min – 24 hours |
| Org chart / People search | Up to 24–48 hours |
| SharePoint / OneDrive | 5–30 minutes |
| Global Address List | Up to 24 hours |
idtyp=user tokens)| Error | Cause | Fix |
|---|---|---|
Agent user IdentityParent does not exist | identityParentId points to a non-existent or non-agent-identity object | Verify the ID is an agentIdentity service principal, not a regular app |
400 Bad Request (identityParentId already linked) | The agent identity already has an agent user | Each agent identity supports only one agent user |
409 Conflict on UPN | The userPrincipalName is already taken | Use a unique UPN |
Weekly Installs
7.3K
Repository
GitHub Stars
26.7K
First Seen
Feb 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex7.2K
gemini-cli7.2K
opencode7.2K
cursor7.2K
github-copilot7.2K
amp7.1K
97,600 周安装
identityParentId | String | Object ID of the parent agent identity |
| License assignment fails | Usage location not set | Set usageLocation before assigning licenses |