Sitemap
Open in app

Sign in

Medium Logo
Write
Search

Sign in

Agent Identity demystified

Derk van der Woude

--

This blog series aims to demystify Microsoft Entra Agent Identity Security.

Since all features are in status Preview, we need to use the Microsoft Graph /beta endpoint to get access.

Let’s start to answer the question why another identity type for the AI Agent entity?

Responsible AI (RAI) is an ethical framework for trustworthy and safe user of AI. Two core principles are accountability, ensuring responsibility of the AI Agent, and transparency, providing insight in whom users are communication with (e.g. AI bot.

The first part describes the Agent building platforms and the Agent Identity platform, which is required for the Entra security products.

The Defender for Cloud Copilot Studio Agent Security is covered in the ‘real-time protection during agent runtime’ and ‘AI Agents Inventory’ blog.

Agent Building platforms

Press enter or click to view image in full size
Figure 1. Agent Building Platforms

Agent Building platforms are the products where agents are available or can be created.

Copilot Studio → low-code / no-code agent builder for business apps (M365, Dynamics, Power Platform, connectors, workflows).

ATTOW: Copilot Studio Agents are created as Service Principals, called Classic Agents. The setting below enables modern Agents as Agent Identities which can be used with the Entra Security products.
Power Platform Admin Center -> Copilot -> Settings -> Copilot Studio

Press enter or click to view image in full size
Figure 2. Entra Agent Identity for Copilot Studio setting

Azure AI Foundry → pro-code / developer-first platform for building, evaluating, fine-tuning, and deploying agents and models.

Early AI Foundry Agents were created as Service Principals, called Classic Agents. ATTOW all AI Foundry Agents are modern Agents as Agent Identities which can be used with the Entra Security products.

Security Copilot → a generative AI-powered security platform. It’s a natural language, assistive copilot experience in the Microsoft Security products like Microsoft Defender, Purview, Entra and Intune. Additionally, it serves as an automation platform for Security Agents.

Microsoft 365 Copilot is integrated Microsoft Agent itself for Microsoft 365 apps.

Third-party agents are non-Microsoft custom agents.

Agent Identity platform

Press enter or click to view image in full size
Figure 3. Agent Identity platform

The Agent Identity platform exists of 4 core components: Agent Identity Blueprint, Agent Identity Blueprint Principal, Agent Identity and Agent User (optional).

The easiest way to get an Agent Identity is to create an Agent in one of the three Microsoft Building platforms above. If you want to understand the architecture and create a custom Agent please continue reading.

Agent Identity Blueprint

Agent Identity Blueprint is a parent template for creating Agent Identities [1:N]. The Blueprint is also a container for IT management.

At the time of writing an Agent Identity Blueprint can only be created via the Microsoft Graph API, not via the UI.

The Agent Identity Blueprint has (* = required) the following parameters:

  • *Display name of the Agent Identity Blueprint
  • Owner (user) is the technical administrator responsible for operational management, including setup, configuration, and credential management. An Agent Blueprint is highly advised to have an Owner.
  • *Sponsor (user or group) is the business representative accountable for the agent’s purpose and lifecycle. An Agent Blueprint requires a Sponsor.
  • Publisher is the building platform org of the agent, it can be custom or Copilot Studio, AI Foundry, etc.
  • *Credentials used to access resources in the Tenant

Create Agent Identity Blueprint via PowerShell Graph API

# Connect Graph with required scopes
Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create"

# Define these variables
$BlueprintDisplayName = "<Agent Blueprint Name>"
$SponsorUserId = "<Sponsor-UserID>"  # Replace with actual user ID
$OwnerUserId = "<Owner-UserID>"     # Replace with actual user ID

# Construct the body for the POST request
$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = $BlueprintDisplayName
    "sponsors@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$SponsorUserId")
    "owners@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$OwnerUserId")
} | ConvertTo-Json -Depth 5

# Make the POST request to create the agent identity blueprint application
$blueprint = Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/applications/graph.agentIdentityBlueprint" -Body $body -ContentType "application/json"

# Output the response
$blueprint

# Close the Graph
Disconnect-MgGraph

‘Write’ down the appId which is required in the next steps.

The /beta is used for the API call , and /v1.0 for the user reference URIs inside the body.

To create an Agent Identity Blueprint we need AgentIdentityBlueprint.Create Graph permissions. To verify permissions in the PowerShell session use:

Get-MgContext | Select -Expand Scopes

Permissions set on the Blueprint are base permissions (optional) inherited by Agent Identities (not required, the permissions/scope can also be set on individual Agent Identities or user-delegated).

Agents are non-predictable in nature so HPA (High Privileged Access) permissions are not allowed, see the complete list here.

Agent Identity Blueprint Principal

Agent Identity Blueprint Principal is a Service Principal for the Agent Identity Blueprint to be visible in the Entra Portal.

No Agent Identities are connected upon creation of the Blueprint

Press enter or click to view image in full size
Figure 5. Agent Blueprints

Create Agent Identity Blueprint Principal via PowerShell Graph API

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create"
$body = @{
    appId   = "<agent-blueprint-app-id>"
}
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/serviceprincipals/graph.agentIdentityBlueprintPrincipal" -Headers @{ "OData-Version" = "4.0" } -Body ($body | ConvertTo-Json)

# Close the Graph
Disconnect-MgGraph

To create an Agent Identity Blueprint Principal we need AgentIdentityBlueprintPrincipal.Create Graph permissions.

The Blueprint Application ID and object ID are visible in the Entra Portal after the Agent Identity Blueprint Principal is created.

Client Credentials

Client Credentials are configured in the Agent Identity Blueprint (not in the Agent Identity) used to request access tokens via the Agent Blueprint ID (Application ID) to access resources in the Microsoft Tenant.

Managed Identity (Federated Identity Credential) credentials are the most secure (recommended), followed by Client Certificate, with Client Secret being the least secure. For easy of simplicity we will use a secret for this blog.

If you see the following message in your lab/test environment on your Agent Identity Blueprint.

⚠️Client secrets are blocked by a tenant-wide policy. Contact your tenant administrator for more information.

The solution is to disable Password addition restriction in the Entra Portal -> Enterprise Apps -> Application Policies -> Block password addition -> Status Off

Set Blueprint Permissions [Secret] via PowerShell Graph API

Requires PowerShell 7

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All"

$applicationId = "<agent-blueprint-app-id>"

# Define the secret properties
$displayName = "<Secret Name>"
$endDate = (Get-Date).AddYears(1).ToString("o")  # 1 year from now, in ISO 8601 format

# Construct the password credential
$passwordCredential = @{
    displayName = $displayName
    endDateTime = $endDate
}

# Add the password (client secret)
$response = Add-MgApplicationPassword -ApplicationId $applicationId -PasswordCredential $passwordCredential

# Output the generated secret (only returned once!)
Write-Host "Secret Text: $($response.secretText)"

# Close the Graph
Disconnect-MgGraph

To set Agent Identity Blueprint Client Credentials we need AgentIdentityBlueprint.AddRemoveCreds.All Graph permissions.

Write down the secret value.

Check Blueprint Permissions via PowerShell Graph API

Requires the Microsoft.Graph.Applications module

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Read.All"

$applicationId = "<agent-blueprint-app-id>"

# Get application including credentials
$response = Invoke-MgGraphRequest -Method GET `
    -Uri "https://graph.microsoft.com/beta/applications/$applicationId" `
    -OutputType PSObject

# View password credentials
$response.passwordCredentials

# View key credentials  
$response.keyCredentials

# View federated identity credentials
$fedCreds = Invoke-MgGraphRequest -Method GET `
    -Uri "https://graph.microsoft.com/beta/applications/$applicationId/federatedIdentityCredentials"
$fedCreds.value

# Close the Graph
Disconnect-MgGraph

identifier URI and scope

identifier URI and scope are required for incoming requests (from users and agents).

Set Blueprint identifier URI and scope via PowerShell Graph API

Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All"

$AppId = "<agent-blueprint-app-id>"
$IdentifierUri = "api://$AppId"
$ScopeId = [guid]::NewGuid()

$body = @{
    identifierUris = @($IdentifierUri)
    api = @{
        oauth2PermissionScopes = @(
            @{
                adminConsentDescription = "Allow the application to access the agent on behalf of the signed-in user."
                adminConsentDisplayName = "Access agent"
                id = $ScopeId.ToString()
                isEnabled = $true
                type = "User"
                value = "access_agent"
            }
        )
    }
} | ConvertTo-Json -Depth 10

# Use BETA endpoint
$uri = "https://graph.microsoft.com/beta/applications/$AppId"

Invoke-MgGraphRequest -Method PATCH -Uri $uri -Body $body -ContentType "application/json"

# Close the Graph
Disconnect-MgGraph

To set Agent Identity Blueprint identifier URI and scope we need AgentIdentityBlueprint.ReadWrite.All Graph permissions.

Optional to make the Scope inheritable by the Agent Identity, use the inheritablePermissions (collection; e.g. “00000003–0000–0000-c000–000000000000” which is the AppID for the Microsoft Graph) and inheritableScopes(scopes; e.g. “User.Read”, “Mail.Read”) in the body.

Agent Identity

Agent Identity represents the primary identity of the agent within Entra. Agent Identities do not store credentials, but rely on credentials from the parent Agent Identity Blueprint.

Authentication uses multi-stage token exchanges where the Agent Identity Blueprint authenticates using its credentials (FIC, Certificate or Secret), obtains an exchange token (T1), and the token (T1) is used to impersonate the Agent Identity.

The Agent Identity has (* = required) the following parameters:

  • *Display name of the Agent Identity Blueprint
  • *Sponsor is the business representative accountable for the agent’s purpose and lifecycle. An Agent Identity requires a Sponsor.
  • *Blueprint is the template parent Agent Identity Blueprint

To create an agent we need to connect to the Agent Identity Blueprint which creates the Agent Identity.

Create an agent identity

Connect-MgGraph -Scopes "AgentIdentity.Create.All"

$tenantId = "<tenant-ID>"
$AppId = "<agent-blueprint-app-id>"
$clientSecret = "<secret>"
$SponsorUserId = "<Sponsor-UserID>" 
$agentIdName = "<Agent-Identity-Name>" 

# Token endpoint
$tokenUrl = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

# Create the request body
$body = @{
    client_id     = $AppId
    client_secret = $clientSecret
    scope         = "https://graph.microsoft.com/.default"
    grant_type    = "client_credentials"
}

# Get the access token
$response = Invoke-RestMethod -Method POST -Uri $tokenUrl -Body $body -ContentType "application/x-www-form-urlencoded"

$accessToken = $response.access_token

# Use the token to call Microsoft Graph
$headers = @{
    "Authorization" = "Bearer $accessToken"
    "Content-Type"  = "application/json"
}

$SecuredPasswordPassword = ConvertTo-SecureString `
-String $clientSecret -AsPlainText -Force

$ClientSecretCredential = New-Object `
-TypeName System.Management.Automation.PSCredential `
-ArgumentList $AppId, $SecuredPasswordPassword

Connect-MgGraph -TenantId $tenantID -ClientSecretCredential $ClientSecretCredential

$uri = "/beta/servicePrincipals/microsoft.graph.agentIdentity"
$body = @{
  displayName = $agentIdName
  agentIdentityBlueprintId = $AppId
  "sponsors@odata.bind" = @(
    "https://graph.microsoft.com/v1.0/users/$SponsorUserId"
  )
}

Invoke-MgGraphRequest -Method Post -Uri $uri -Body $body -OutputType PSObject

# Close the Graph
Disconnect-MgGraph

To create an Agent Identity Blueprint we need AgentIdentity.Create.All Graph permission.

The Agent Identity is created by the Agent Identity Blueprint via an Access Token. To verify the Access Token use a JWT Decoder (insert the output of $accessToken in the JWT decoder).

Press enter or click to view image in full size
Figure 6. AccessToken -> JWT example

The agent is created by the Agent Identity Blueprint and connected to the Agent Identity Blueprint.

Press enter or click to view image in full size
Figure 7. Agent Identities

Agent Identities can be secured by Identity Protection, Conditional Access, Access Reviews, etc. This will be discussed in the next blog-series.

Agent User

Agent User (optional) is a special type of identity to add human capabilities (autonomous) to an agent. An agent user is always connected to an agent identity (1:1). Authentication occurs via an access token issued to the associated agent (Blueprint token -> Agent Identity token -> Agent User token).

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.ReadWrite.All"

# Create the body
$body = @{
    "@odata.type" = "microsoft.graph.agentUser"
    displayName = "<Agent User Name>"
    userPrincipalName = "<Agent User UPN>"
    identityParentId = "<Agent-Identity-ID>"
    mailNickname = "<Agent User mailNickname / Alias>"
    accountEnabled = $true
}

# Make the request
$response = Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/beta/users" `
    -Body ($body | ConvertTo-Json) `
    -ContentType "application/json" `
    -Headers @{ "OData-Version" = "4.0" }

# Display result
Write-Host "✓ Agent User created successfully!" -ForegroundColor Green
$response

# Close the Graph
Disconnect-MgGraph

Agent Users can be added to Microsoft Entra groups, access resources (e.g. Microsoft 365 Apps), assigned licenses, etc.

Press enter or click to view image in full size
Figure 8. Agent User

The Agent User is visible in the Entra Portal in the Users section, in the details we can see connected Agent ID.

Agent Registry

The Agent Registry is the centralized metadata repository and “source of authority” for Agents in the Microsoft Tenant. The core components of the Agent Registry are:

  • Metadata store is the centralized agent metadata repository
  • Collections is used for agent categorization and discovery (Global and Quarantined are the default collections)
Press enter or click to view image in full size
Figure 9. Agent Identity Security Architecture

So far for the first part of the blog series, I hope it was informative and see you in the next one where we will discuss the Entra & Defender Security products related to Agent Identities.

--

--

Derk van der Woude
Derk van der Woude

Written by Derk van der Woude

623 followers
3 following

Microsoft Security MVP