Microsoft Entra agent user
Create one passwordless agent user with a validated Agent ID parent and explicit governance.
When to invoke
- Give a Microsoft Agent ID agent a user-shaped Entra identity.
- Enable approved mailbox, Teams, group, or organizational-directory scenarios.
- Validate an existing agent user's identity parent.
- Configure an optional manager, usage location, or license.
Prerequisites and context
- Microsoft Entra tenant and an existing Agent ID service identity.
- Least-privilege Graph permission, preferably
AgentIdUser.ReadWrite.IdentityParentedBy.
- Required delegated/admin role and explicit approval for user or license creation.
- Unique UPN and mail nickname; one agent user is allowed per parent identity.
Criteria
identityParentId is the object ID of an agent identity with
servicePrincipalType: ServiceIdentity, not a regular application service principal.- Agent users have no password; authentication is derived from the parent identity.
userPrincipalName is unique in the tenant.- Set
usageLocation before assigning a license.
- Manager assignment is optional and uses a valid directory user reference.
Procedure
- Confirm business purpose, data access, lifecycle owner, UPN, manager, and license requirement.
- Read the parent service principal and verify the Agent ID identity type.
- Check whether the parent already has an agent user; stop on the one-to-one constraint.
- Create the agent user with
accountEnabled, displayName, mailNickname, unique UPN, and
identityParentId.
- Optionally assign a manager.
- If licensing is approved, set usage location first, then assign the exact SKU.
- Verify parent linkage, directory identity, lifecycle owner, and expected token/user behavior.
Creation shape:
{
"@odata.type": "#microsoft.graph.agentUser",
"accountEnabled": true,
"displayName": "<display-name>",
"mailNickname": "<alias>",
"userPrincipalName": "<unique-upn>",
"identityParentId": "<agent-identity-object-id>"
}
Output template
## Microsoft Entra agent user result
**Status:** CREATED | READY | BLOCKED
**Parent identity:** <object ID and verified type>
**Agent user:** <object ID/UPN or planned value>
### Governance
- Lifecycle owner: <owner>
- Manager: <assigned/not requested>
- Usage location/license: <result/not requested>
- Permissions used: <Graph permission and role>
### Validation
- Parent type and one-to-one check: <pass/fail>
- Agent user linkage: <pass/fail/not run>
Limits
- Do not use a regular app service principal as the identity parent.
- Do not create passwords, assign privileged admin roles, or add role-assignable groups.
- Do not assign licenses without approval, usage location, and a lifecycle owner.
- Do not promise immediate mailbox, Teams, or org-chart propagation; service provisioning is asynchronous.
Related primitives
| Name |
Type |
Use it when |
azure-role-selector |
skill |
Least-privilege Azure RBAC is also required. |
open-horizons-security-reviewer |
agent |
Identity scope or collaboration data needs independent review. |
foundry-agent-blueprint |
skill |
The user identity belongs to a Foundry agent design. |
Quality gate
References
1---2name: azure-entra-agent-user-23description: Designs and provisions a Microsoft Entra agent user linked to an Agent ID identity, including parent validation, least-privilege permissions, optional manager, usage location, licensing, and verification. Use when an agent needs a user-shaped directory identity for collaboration workloads.4---56# Microsoft Entra agent user78Create one passwordless agent user with a validated Agent ID parent and explicit governance.910## When to invoke1112- Give a Microsoft Agent ID agent a user-shaped Entra identity.13- Enable approved mailbox, Teams, group, or organizational-directory scenarios.14- Validate an existing agent user's identity parent.15- Configure an optional manager, usage location, or license.1617## Prerequisites and context1819- Microsoft Entra tenant and an existing Agent ID service identity.20- Least-privilege Graph permission, preferably `AgentIdUser.ReadWrite.IdentityParentedBy`.21- Required delegated/admin role and explicit approval for user or license creation.22- Unique UPN and mail nickname; one agent user is allowed per parent identity.2324## Criteria2526- `identityParentId` is the object ID of an agent identity with27 `servicePrincipalType: ServiceIdentity`, not a regular application service principal.28- Agent users have no password; authentication is derived from the parent identity.29- `userPrincipalName` is unique in the tenant.30- Set `usageLocation` before assigning a license.31- Manager assignment is optional and uses a valid directory user reference.3233## Procedure34351. Confirm business purpose, data access, lifecycle owner, UPN, manager, and license requirement.362. Read the parent service principal and verify the Agent ID identity type.373. Check whether the parent already has an agent user; stop on the one-to-one constraint.384. Create the agent user with `accountEnabled`, `displayName`, `mailNickname`, unique UPN, and39 `identityParentId`.405. Optionally assign a manager.416. If licensing is approved, set usage location first, then assign the exact SKU.427. Verify parent linkage, directory identity, lifecycle owner, and expected token/user behavior.4344Creation shape:4546```json47{48 "@odata.type": "#microsoft.graph.agentUser",49 "accountEnabled": true,50 "displayName": "<display-name>",51 "mailNickname": "<alias>",52 "userPrincipalName": "<unique-upn>",53 "identityParentId": "<agent-identity-object-id>"54}55```5657## Output template5859```markdown60## Microsoft Entra agent user result6162**Status:** CREATED | READY | BLOCKED63**Parent identity:** <object ID and verified type>64**Agent user:** <object ID/UPN or planned value>6566### Governance67- Lifecycle owner: <owner>68- Manager: <assigned/not requested>69- Usage location/license: <result/not requested>70- Permissions used: <Graph permission and role>7172### Validation73- Parent type and one-to-one check: <pass/fail>74- Agent user linkage: <pass/fail/not run>75```7677## Limits7879- Do not use a regular app service principal as the identity parent.80- Do not create passwords, assign privileged admin roles, or add role-assignable groups.81- Do not assign licenses without approval, usage location, and a lifecycle owner.82- Do not promise immediate mailbox, Teams, or org-chart propagation; service provisioning is asynchronous.8384## Related primitives8586| Name | Type | Use it when |87| --- | --- | --- |88| `azure-role-selector` | `skill` | Least-privilege Azure RBAC is also required. |89| `open-horizons-security-reviewer` | `agent` | Identity scope or collaboration data needs independent review. |90| `foundry-agent-blueprint` | `skill` | The user identity belongs to a Foundry agent design. |9192## Quality gate9394- [ ] Parent is verified as an Agent ID service identity.95- [ ] No existing agent user is linked to the parent.96- [ ] UPN, owner, manager, and license intent are explicit.97- [ ] No password or excessive permission is introduced.98- [ ] Linkage and optional license state are verified without exposing tokens.99100## References101102- [Microsoft Entra Agent ID documentation](https://learn.microsoft.com/entra/agent-id/)
paulasilvatech