Entra Agent ID object model

Why this matters

Microsoft introduced four new object types in the directory for agents. Every architecture mistake anyone makes with this stack is downstream of confusing them. Get this right on day one and everything else in Module 10 will click; get it wrong and you'll build the wrong permission model, pick the wrong OAuth flow, and lose sponsor accountability.

Cross-ref: this maps directly to Lesson 2.1 (Agent identity patterns). If you internalise both lessons, you can walk into any Entra tenant and translate its objects to your Keycloak / Auth0 mental model in ten minutes.

Learning objectives

1. Distinguish the four Entra agent object types and the relationships between them.
2. Know when you need an agent's user account and when to avoid it.
3. Know why an agent identity is not just a service principal with a special tag.
4. Provision the objects correctly (blueprint first, then identity, then optional user).
5. Recognise the sign-in / audit log claims each object emits.

1. The four objects at a glance

    +-------------------------------+
    |   Agent identity blueprint    |     the TEMPLATE + credential holder
    |   (application in Entra)      |
    +--------+------------+---------+
             |            |
             | multitenant/single-tenant
             v            v
    +-------------------------------+
    | Agent identity blueprint      |     tenant-local runtime presence
    | principal                     |     of the blueprint
    +----------------+--------------+
                     |
                     | creates 1..N
                     v
    +-------------------------------+
    |        Agent identity         |     the AGENT ITSELF as a principal
    |   (subtype: service principal)|     idtyp = agent
    +------+------------------------+
           |
           | optional 1:1
           v
    +-------------------------------+
    |     Agent's user account      |     digital-worker persona
    |   (subtype: user)             |     idtyp = user
    +-------------------------------+

Relationships you must memorise:

• Blueprint → many agent identities (1:many).
• Agent identity → at most one agent's user account (0..1).
• The parent link is immutable once created.

2. The agent identity blueprint — the template

This is what Microsoft calls the "template"; it is technically an Entra ID Application object with an agent subtype and an extra Graph permission AgentIdentity.CreateAsManager.

Think of the blueprint as a class definition for a family of agents. It defines:

• Verified publisher — who built the agent.
• Description + tags — what this class of agents does.
• App roles — role names your APIs will grant to agents.
• Optional claims — extra fields to include in tokens.
• Required resource access (requiredResourceAccess) — static declaration of what APIs / scopes the agent needs. Admins review this at consent time (Lesson 10.4).
• Inheritable permissions — resource apps whose grants should cascade to all child agent identities (Lesson 10.4).
• Credentials — the actual secret / certificate / managed identity used to impersonate the child identities. Client secrets are discouraged in production; use FIC + managed identity or certificates.
• Federated Identity Credentials (FIC) — declare trust in an external issuer (Entra managed identity, GitHub OIDC, AWS STS, SPIFFE) so the blueprint never holds a shared secret.

Key rule: the blueprint holds credentials; the agent identity holds permissions. A compromise of the blueprint's credentials compromises all its child agent identities, which is why the number of blueprints per environment is a security boundary decision.

You can make blueprints single-tenant (created and used in the same tenant) or multitenant (published so other customers can add them to their tenant — this is how ISVs distribute agents).

3. The agent identity blueprint principal — the tenant-local runtime object

When a blueprint is added to a tenant (yours, or a customer's for multitenant), Entra creates a service-principal-shaped object in that tenant. This is what actually calls Microsoft Graph to spawn agent identities. It has:

• An OAuth client_id.
• The credentials configured on the blueprint (or the customer's own overrides).
• The AgentIdentity.CreateAsManager permission.

Why bother with this separate object? Because a blueprint principal creates and audits every agent-identity provisioning event. Its oid shows up in Entra audit logs. Delete the principal → the blueprint is effectively removed from the tenant (no more agents can be created from it).

If you already know Entra: application ↔ blueprint and service principal ↔ blueprint principal. Same relationship, agent-tenanted subtype.

4. The agent identity — the acting principal

This is the object your customers reason about when they say "the agent".

It's a service principal in Entra ID, single-tenant, with subtype = agent. Its distinguishing traits:

• Has its own client_id (called AgentIdentity) and oid.
• Does not own credentials. It authenticates only via the parent blueprint's impersonation.
• Can be granted permissions directly (Graph app perms, Azure RBAC roles, some Entra directory roles — see Lesson 10.4).
• Can also inherit delegated permissions from its blueprint via inheritable permissions.
• Emits sign-in logs with the agent identity as the acting client + a claim identifying the blueprint that impersonated it.
• Can be assigned a sponsor and an owner (Lesson 10.7).
• Can be a member of Entra groups except role-assignable groups.

Naming convention that scales: prefix the display name with the class + purpose, e.g. Agent-HR-OnboardingBot-01, Agent-CRM-HelpdeskV2-prod-eu-023. Microsoft's admin center searches by display name, so pick a scheme that filters cleanly.

Every agent identity has exactly one parent blueprint, immutably. You can't "reparent" an agent.

5. The agent's user account — digital-worker persona

Some agents need to look and feel like a real employee: a mailbox, Teams presence, appear in the org chart, participate in @mentions, receive Word comments. For those, and only those, you create an agent's user account.

Properties:

• It's a user object in Entra (idtyp = user), so it can be assigned licences, added to distribution groups, mentioned in Teams, receive email.
• 1:1 with an agent identity. Each agent identity has at most one user account; each user account has exactly one parent agent identity, itself with exactly one parent blueprint.
• Cannot have passwords, passkeys, MFA factors, or any interactive credentials. The only credential it supports is "prove you are my parent agent identity" via the blueprint's impersonation chain.
• Cannot be assigned privileged admin roles.
• Cannot be added to role-assignable groups or granted custom roles.
• Typically has permissions like a guest user, plus enumeration on users/groups.

Provisioning path matters:

• Via Microsoft Graph directly — creates the identity but does not provision mailbox / OneDrive / Teams presence.
• Via Microsoft Teams / Agent 365 SDK — full digital-worker provisioning including M365 resources (subject to appropriate licence assignment — E5, Teams Enterprise, Copilot).

Mailbox / OneDrive provisioning is asynchronous and typically completes within 10-15 minutes but can take up to 24 hours.

When NOT to create one: if the agent can do its job with app credentials or on-behalf-of tokens, skip it. Every user account you create is one more thing to license, group, review, and eventually deprovision.

6. Object-to-log mapping (memorise this)

Auditors will ask "how do I know which principal did what?" — here's the answer.

The three-way separation between blueprint principal (creator), agent identity (permission holder + auditable client), and agent user account (user-shaped subject) is exactly what lets you write a Splunk query like:

sourcetype=entra_signin
| where idtyp="agent" and app_display_name="Agent-CRM-HelpdeskV2-prod-eu-023"
| stats count by resource_display_name

and get a complete view of what one agent touched, without conflating it with the blueprint or the digital-worker mailbox.

7. Creating the objects (minimum viable flow)

You'll usually use Microsoft Foundry / Copilot Studio / Agent 365 CLI / Teams Developer Portal for this. The raw Graph is shown so you can automate.

7.1 Create the blueprint (as an app)

POST https://graph.microsoft.com/v1.0/applications
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "displayName": "MTN CRM Helpdesk Agent",
  "signInAudience": "AzureADMyOrg",
  "tags": ["agent", "crm", "helpdesk"],
  "verifiedPublisher": { "verifiedPublisherId": "1234567" },
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000003-0000-0000-c000-000000000000",
      "resourceAccess": [
        { "id": "df021288-bdef-4463-88db-98f22de89214", "type": "Scope" }   // User.Read
      ]
    }
  ]
}

(You'd then flip the app subtype to agent; the Agent 365 CLI does this for you — the raw Graph subtype API surface is still previewing at time of writing.)

7.2 Consent + create the blueprint principal

An admin consents the blueprint into the tenant. Entra creates the blueprint principal automatically. Grant it AgentIdentity.CreateAsManager (app permission) so it can spawn identities.

7.3 Create an agent identity

POST https://graph.microsoft.com/v1.0/agentIdentities
Authorization: Bearer <blueprint-principal-token>

{
  "displayName": "Agent-CRM-HelpdeskV2-prod-eu-023",
  "parentBlueprintId": "<blueprint-application-id>",
  "notes": "Prod helpdesk agent, EU region, deployment 023",
  "sponsorId": "<owner-user-oid>"
}

7.4 (Optional) Create the agent's user account

POST https://graph.microsoft.com/v1.0/agentUserAccounts
Authorization: Bearer <blueprint-principal-token>

{
  "parentAgentId": "<agent-identity-oid>",
  "displayName": "Helpdesk Bot",
  "mailNickname": "helpdesk-bot-023",
  "usageLocation": "ZA"
}

Then assign a licence (Teams Enterprise + M365 Copilot at minimum) for the digital-worker features. Mailbox provisioning follows within minutes.

8. Reference architecture: how the pieces sit in production

Take a real deployment (mirrors MTN's reference architecture in the Agentic AI syllabus):

• 1 blueprint per class of agent — e.g. crm-helpdesk, momo-fraud-triage, onbiller-billrun. Each has its own credential (FIC → Azure managed identity) and its own inheritable-permission profile.
• N agent identities per environment — agent.crm-helpdesk.dev-01, agent.crm-helpdesk.prod-023, etc. Each has a sponsor (accountable manager) and an owner (technical lead).
• User account only for a few — e.g. the fraud triage agent that emails compliance and posts in Teams gets one; the billrun agent that only writes to BSS APIs does not.

Rule of thumb from the MTN engagement: if it doesn't need a mailbox, it doesn't get a user account.

9. Common pitfalls

1. Sharing a blueprint across dev / test / prod. A shared blueprint means shared credentials + shared inheritable permissions — one dev leak, and prod is exposed. Use separate blueprints per environment (or at minimum separate FICs per environment).
2. Creating a user account "just in case". Every account you create is licensed, mailbox-provisioned, DLP-scoped, MFA-exempt, and needs deprovisioning. Only create when the agent must appear as a person.
3. Assigning permissions on the blueprint instead of the identity. Blueprint permissions cascade to all children if inheritable — great for baseline, dangerous for anything sensitive. Grant sensitive scopes on individual agent identities.
4. Trying to give an agent user an admin role. Blocked by design. Use the parent agent identity for admin-shaped work; use the user account only where a user token is required.
5. Renaming display names as your governance signal. Names change; use sponsor, owner, and custom security attributes (Lesson 10.5) for governance queries.
6. Not filtering by subtype in the admin center. The "All agent identities" pane also lists legacy service principals used by pre-Agent-ID agents; filter to the agent subtype to see only the new model.
7. Forgetting the immutable parent link. If you get the parent wrong at creation, you have to delete + recreate. Get the naming and the parent right on the first Graph POST.

10. Hands-on lab (2 h)

1. In a test Entra tenant, register a new agent identity blueprint using the Agent 365 CLI (agent365 blueprint create). Note the blueprintId and the blueprint principal oid.
2. Attach an FIC to the blueprint pointing at an Azure managed identity you own. Verify the blueprint has no client secret.
3. Create three agent identities from the blueprint (dev, staging, prod) with distinct display names + sponsors.
4. Grant User.Read (delegated) on the blueprint principal; mark Microsoft Graph as inheritable.
5. Sign in as one of the agent identities using the sidecar SDK (Lesson 10.3 lab) and inspect the returned token. Confirm idtyp=agent, oid = agent identity, and Graph delegated scope User.Read is present without a per-identity consent grant.
6. Create an agent's user account for the prod identity via Teams; verify a mailbox is provisioned within ~15 minutes.
7. Query https://graph.microsoft.com/v1.0/agentIdentities?$filter=parentBlueprintId eq '<blueprintId>' — should return three identities.
8. Delete the dev identity. Confirm its child agent user account (if any) is deleted automatically.

11. Self-check

1. What is the difference between a blueprint and a blueprint principal? What does each do?
2. Why is the agent user account 1:1 with an agent identity (and not 1:many)?
3. Can you re-parent an agent identity? Why not?
4. Which of the four objects can be granted app permissions? Which cannot?
5. When would you deliberately choose not to create an agent user account?
6. Which idtyp value does each of the four objects emit in tokens?

12. References

• Microsoft Entra Agent ID — what are agent identities
• Agent identity blueprints
• Agent's user account
• Agent identities, service principals, and applications
• Vendor-neutral Lesson 2.1 (Agent identity patterns) — the mental-model prerequisite.