Edit

Migrate custom app registrations to Agent ID

If you built AI agents by using standard Microsoft Entra app registrations or service principals, your agents authenticate like any other application. They don't take advantage of agent-specific governance capabilities like Conditional Access policies, centralized audit logging, and lifecycle management that Agent ID provides.

This article shows you how to migrate agents where you own the code and the identity configuration to Agent ID. You create Agent ID resources (a blueprint and agent identity), update your application code, and decommission the old identity. For agents created through Microsoft Copilot Studio, see Migrate Copilot Studio agents to Agent ID.

Prerequisites

  • An existing AI agent that uses an app registration or service principal for authentication.
  • Agent ID Developer or Agent ID Administrator role to create blueprints and agent identities.
  • Privileged Role Administrator role to grant Microsoft Graph application permissions.
  • Access to the Microsoft Graph v1.0 API.
  • Familiarity with Agent ID key concepts. For more information, see Agent identity concepts.

Licensing requirements

Microsoft Entra Agent ID is a product within Microsoft Entra that provides the platform for creating and managing agent identities and agent identity blueprints. Agent ID is available for all Microsoft Entra customers.

Microsoft Agent 365 enables agents to operate across Microsoft 365 services and enterprise workflows, which requires a Microsoft Agent 365 license for each user. For pricing details, see Microsoft Agent 365 plans and pricing.

Extending Microsoft Entra security features to agents requires Microsoft 365 E7 (includes Agent 365 and Microsoft Entra Suite) or Microsoft 365 E5 paired with a Microsoft Agent 365 license. Customers without E5 or E7 can use the following standalone licensing options with a Microsoft Agent 365 license:

  • Conditional Access for agents: Microsoft Entra ID P1
  • ID Protection for agents: Microsoft Entra ID P2
  • ID Governance for agents: Microsoft Entra ID P1
  • Network controls for agents: Microsoft Entra Internet Access, included in Microsoft Entra Suite or licensed separately. For more information, see What is Global Secure Access.

Review migration benefits

Microsoft Entra Agent ID provides specialized identity constructs for AI agent authentication and authorization. Agent identity blueprints serve as governance templates, and agent identities are the runtime principals your agents use to authenticate, acquire tokens, and access resources. By migrating to Agent ID, you get:

Agent ID brings your agents under the same governance model as users and workloads. Moving to Agent ID gives you:

Access control

  • Conditional Access enforcement. Apply Conditional Access policies and controls directly to agents and the resources they access, just as you would for users.

Agent governance

  • Lifecycle management. Microsoft Entra ID Governance can manage agent access lifecycle policies, so agents don't accumulate stale permissions.
  • Multi-cloud visibility. Agents operating across Azure, on-premises, and other cloud environments are governed through a single identity plane.

Visibility and audit

  • Agent-specific audit trails. Audit and sign-in logs attribute agent actions and the resources they access to the specific agent identity, not a generic app registration. This approach makes investigation and attribution straightforward.
  • Agent registry visibility. Agents appear in your organizational agent registry, giving you a complete inventory instead of blind spots.

Risk and protection

  • ID Protection coverage. ID Protection monitors for anomalous agent behavior, giving you risk-based detection and automated remediation.

Review the migration phases

Migrating to Agent ID is a phased process, not a single-step switch. This guide organizes the process into four phases, each building on the outputs of the previous one. The phased model prevents premature deletion of service principals that might support active workloads. Proper discovery and classification occur before any migration or decommission action.

Phase Goal Key output
Discover Inventory all agent-related identities in your tenant: service principals, app registrations, and their usage signals. A structured report or dashboard with identity metadata, sign-in activity, permissions, ownership, and builder origin for each agent.
Classify Categorize each identity by usage level and origin. A prioritized action plan: which identities to clean up, which to migrate, and which to leave as-is.
Migrate Create Agent ID resources (blueprint + agent identity) and update your agents to use them. New agent identities running on Agent ID with matching permissions and credentials.
Validate and decommission Confirm the new identity works end-to-end, parallel-run if needed, then retire the legacy identity with safeguards. Legacy identities removed; agents running fully on Agent ID.

Phase 1: Discover existing app registrations

Before migrating anything, build a complete inventory of the agent-related identities in your tenant. Start with an organization-wide sweep to find all migration candidates, then narrow down to individual agents to capture the configuration details you need during migration.

Create an organization-level inventory

Scan your tenant for all service principals that might represent AI agents. The goal is to create a structured report that surfaces usage signals and helps you classify each identity in the next phase.

For each candidate service principal, capture:

  • Identity metadata: display name, application ID, object ID, creation date, tenant.
  • Ownership: assigned owners, owning team or department (where available).
  • Sign-in activity: last interactive and non-interactive sign-in, sign-in count over 30, 90, and 180 days.
  • Audit log signals: source system that created the service principal, creation event, recent modifications, or permission changes.
  • Tag analysis: tags applied to the service principal; check whether it carries any builder-specific tag patterns.
  • API permissions: delegated and application permissions granted, admin consent status, permission sensitivity level.
  • Other identity configurations: credentials used, OAuth flows, custom attributes, RBAC role assignments, redirect URIs, and any downstream dependencies. You need these configuration details during migration to correctly recreate the identity as an Agent ID.

Tip

You can pull most of the configuration details programmatically by using Microsoft Graph. Use the GET /applications and GET /servicePrincipals endpoints to pull permissions, credentials, ownership, and more. For OAuth flows your application uses and any downstream dependencies, check your application code.

Identify agents through log and permission analysis

For service principals that don't have tags, use behavioral and configuration signals to identify likely agent identities. No single signal is definitive. Weight them in combination to produce a confidence score.

Signal category What to look for Why it indicates an agent
API permissions Application permissions targeting Bot Framework, Azure OpenAI, Azure AI Services, or Cognitive Services APIs. Agents require these APIs to function; traditional applications rarely request them together.
Redirect URIs URIs pointing to token.botframework.com, botframework.com, or Azure Bot Service endpoints. These URIs are Bot Framework callback URLs used exclusively by conversational agents.
Sign-in patterns Non-interactive or service principal sign-ins with high frequency and no associated user context. Agents authenticate autonomously; human-facing apps typically have interactive sign-in activity.
Token audience Tokens requested for https://api.botframework.com, Azure OpenAI endpoints, or AI Services endpoints. The token audience reveals what resource the service principal is calling.
Resource group association Service principal linked to a resource group containing Bot Service, Azure OpenAI, or AI Search resources. Co-location with AI infrastructure suggests the service principal serves an agent workload.
Naming conventions Display names containing terms like agent, bot, copilot, assistant, or orchestrator. While not deterministic, naming patterns correlate strongly with agent workloads when combined with other signals.

To operationalize heuristic discovery, query service principal sign-in logs and permission grants programmatically with Microsoft Graph. For tenants with extended log retention (through Microsoft Sentinel or another SIEM), expand the analysis window beyond Microsoft Entra's default 30-day sign-in retention to improve signal accuracy.

Heuristic discovery produces candidates, not confirmed agents. Review every match before proceeding to classification. Expect false positives, such as backend microservices that call Azure OpenAI but aren't autonomous agents.

Discover agents through organizational knowledge sources

Automated methods might not find every agent, especially custom-built agents with generic API permissions and no naming convention overlap are invisible to tag-based and heuristic scanning. You should therefore consider:

CMDB and asset inventory reconciliation

Cross-reference your discovered service principals against your organization's Configuration Management Database or application portfolio registry. Applications registered as "AI agent," "chatbot," or "virtual assistant" workload types in the CMDB should be matched to their corresponding service principals and added to the migration inventory.

Developer self-attestation

For tenants with large numbers of app registrations, publish the migration inventory to application owners and ask them to attest whether their service principal represents an AI agent. This approach scales discovery beyond what any automated scan can achieve, because the application owner has definitive knowledge of the workload type. Combine self-attestation with a deadline and escalation path to drive completion.

Run these methods in order:

  1. Tag-based scan: Automatically identify all tagged agents. These agents are confirmed candidates.
  2. Heuristic analysis: Scan remaining untagged service principals for behavioral signals. Flag high-confidence matches as probable candidates.
  3. CMDB reconciliation: Match remaining service principals against your asset inventory to catch agents registered under non-obvious names.
  4. Developer attestation: Publish the residual unmatched list to application owners for final classification.

Phase 2: Classify agent identities for migration

Using the discovery report, classify each service principal by usage level, which determines how you proceed with the migration.

Usage Signals Recommended action
Low No sign-in activity in 30+ days, no owner assigned, no API permissions in active use. Candidate for cleanup. Skip migration; decommission directly (Phase 4).
Medium Some recent sign-in activity, non-production permissions, identifiable owner. Candidate for migration. Proceed through Phases 3–4 with standard validation.
High Frequent sign-ins, production API permissions, active workflows dependent on the SP. Migrate with extreme caution. Requires extended parallel run (Phase 4), rollback plan, and stakeholder sign-off.

The 30-day sign-in threshold is based on Microsoft Entra's default retention period. If your organization has audit log retention through Microsoft Sentinel or another SIEM, adjust thresholds accordingly.

Phase 3: Migrate app registrations to Agent ID

This phase covers the technical migration steps for agents whose identity was created as a standard app registration or service principal. You create new Agent ID resources and update your application code to use the two-stage token acquisition model. Steps 1 through 3 target the Microsoft Entra tenant. Step 4 targets changes to your application code.

Important

There's no in-place conversion that transforms an existing app registration or service principal into an agent identity. Migration requires creating a new agent identity alongside your existing identity, then transitioning your agent to use it.

Step 1: Create an agent identity blueprint

To complete this step, you need the Agent ID Developer or Agent ID Administrator role to create blueprints and agent identities, and the Privileged Role Administrator role to grant Microsoft Graph application permissions.

The blueprint is the governance template for your agent. It defines credentials and permission policies that all agent identities created under it inherit.

Create the blueprint using Microsoft Graph:

POST https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint
Content-Type: application/json

{
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-id>"
    ],
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<owner-user-id>"
    ]
}

Or use PowerShell:

$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = "My Agent Blueprint"
    "sponsors@odata.bind" = @("https://graph.microsoft.com/v1.0/users/<sponsor-user-id>")
    "owners@odata.bind" = @("https://graph.microsoft.com/v1.0/users/<owner-user-id>")
} | ConvertTo-Json -Depth 5

Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint" `
    -Headers @{ "OData-Version" = "4.0" } `
    -Body $body `
    -ContentType "application/json"

Important

You create credentials on your blueprint, not on individual agent identities. Configure the federated identity credential on the blueprint before creating agent identities.

Configure credentials on the blueprint

Agent ID uses federated identity credentials (FIC) as the recommended credential type. Managed identities are the preferred option for production deployments because they eliminate secret management. Client secrets and certificates are also supported for production use. To reduce migration effort, consider reusing the same credential type your existing app registration uses.

The recommended credentials depend on your hosting environment:

Hosting environment Recommended credential Notes
Azure (App Service, AKS, Container Apps, VMs) User-assigned managed identity Most secure for production. No secret management required.
Non-Azure cloud (AWS, GCP) Federated identity credential with external IDP Configure workload identity federation with your cloud provider.
On-premises or local development Client secret or certificate Certificates are recommended over client secrets for production on-premises deployments. Use client secrets for local testing only.

After you configure the credential, create a service principal for the blueprint. The service principal is required before you can create agent identities under the blueprint:

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-Type: application/json

{
    "appId": "<blueprint-app-id>"
}

Step 2: Create the agent identity

To complete this step, you need the Agent ID Developer or Agent ID Administrator role.

The agent identity is the runtime principal your agent uses. Create it under a blueprint and assign a sponsor (required), a human user, or group accountable for the agent. Assigning an owner is recommended for management purposes.

POST https://graph.microsoft.com/beta/serviceprincipals/Microsoft.Graph.AgentIdentity
OData-Version: 4.0
Content-Type: application/json

{
    "displayName": "Customer Service Agent - Production",
    "agentIdentityBlueprintId": "<blueprint-app-id>",
    "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-id>"
    ]
}

Record the agent identity's client ID from the response. You need this value when updating your application code.

Step 3: Configure permissions

Replicate the API permissions from your original app registration onto the agent identity. To complete this step, you need the Privileged Role Administrator role to grant application permissions that require admin consent. You have two options:

  • Direct assignment: Assign permissions directly to the agent identity. Use this option when each agent identity needs different permissions.
  • Inherited permissions: Configure permissions on the blueprint and enable inheritance. Use this option when all agent identities under a blueprint share the same permissions.

To replicate Microsoft Graph application permissions, grant the same appRoles to the agent identity's service principal by using the Grant an appRoleAssignment to a service principal API. For delegated permissions, add the required oauth2PermissionGrants by using the Create oAuth2PermissionGrant API. Ensure admin consent is granted for application permissions that require it.

Configure OBO support (interactive agents only)

If your agent uses the on-behalf-of (OBO) flow to act on behalf of a user, you need to add a custom scope to the blueprint so that front-end applications can request tokens for it. After adding the scope, update your front-end application to request a token for the blueprint's resource instead of the previous resource. For the complete OBO configuration walkthrough, see Interactive agent authentication and authorization flow.

If your original app registration had Azure RBAC role assignments, assign the same roles to the new agent identity's service principal so it can access the required Azure resources at runtime:

New-AzRoleAssignment `
    -ObjectId "<agent-identity-service-principal-id>" `
    -RoleDefinitionName "Contributor" `
    -Scope "/subscriptions/<sub-id>/resourceGroups/<rg-name>"

Step 4: Update application code

Agent ID uses a two-stage token acquisition model. Your agent first acquires a bootstrap token by using the blueprint's credential, then exchanges it for an agent-specific token. For more information on updating your code, see these scenarios:

Phase 4: Validate and decommission

After migrating an agent identity, validate that the new Agent ID works correctly before decommissioning the old identity.

Validate the migrated agent identity

Check How to verify Expected result
Token acquisition Run your agent and inspect the token response. Agent successfully acquires tokens using the two-stage flow. No authentication errors.
API access Exercise all API calls the agent makes. All downstream APIs return expected results. No 401/403 errors.
Sign-in logs Microsoft Entra admin center > Sign-in logs, filter by the new agent identity. Sign-in events appear for the new agent identity with successful status.
Audit logs Microsoft Entra admin center > Audit logs. Agent ID creation and permission assignment events are logged.
Conditional Access Review CA policies that target the resource. CA policies evaluate correctly for the new agent identity. No unexpected blocks.

Run old and new identities in parallel

For agents with high usage, run the old and new identities side by side before switching over:

  1. Deploy a parallel instance of your agent configured with the new Agent ID.
  2. Route a percentage of traffic to the new instance (start with 5–10%).
  3. Monitor both instances for errors, latency differences, and permission issues.
  4. Gradually increase traffic to the new instance over one to two weeks.
  5. Once 100% of traffic runs on the new identity, proceed to decommission.

Use feature flags or traffic-splitting infrastructure to control the rollout. This approach lets you revert to the old identity instantly if issues arise.

Decommission safeguards

After you validate the new Agent ID and it carries production traffic, decommission the old identity. Follow these safeguards to minimize risk:

  • Pre-deletion snapshot: Export the service principal's metadata, permissions, and audit history before deletion. This export provides a rollback reference if anything was missed during validation.
  • Phased batches: If you're decommissioning multiple identities, delete in small batches (20-50 service principals per wave) rather than bulk-deleting all at once.
  • Soft-delete first: Use Microsoft Entra's soft-delete capability (30-day recycle bin for applications) before hard deletion. This step gives you a recovery window.

Decommission the original app registration

To decommission the old identity, follow these steps:

  1. Remove API permissions from the old app registration.
  2. Revoke Azure RBAC role assignments for the old service principal.
  3. Delete or rotate client secrets and certificates on the old app registration.
  4. Delete the app registration (enters 30-day soft-delete).
  5. After 30 days, confirm the app registration is permanently deleted or hard-delete if needed.

Troubleshoot common issues

The following table lists common issues you might encounter during migration and how to resolve them.

Symptom Likely cause Resolution
Token exchange fails with invalid_grant The federated identity credential on the blueprint is misconfigured or the managed identity isn't correctly linked. Verify the FIC subject, issuer, and audience match your hosting environment. Check that the managed identity has the correct assignment.
Audience mismatch error The token request specifies the wrong audience or the blueprint audience doesn't match the target resource. Ensure the token request audience matches the resource you're calling. For Microsoft Graph, use https://graph.microsoft.com/.default.
403 Forbidden on API calls API permissions weren't correctly replicated from the old app registration to the agent identity. Compare the permissions on both identities. Ensure admin consent was granted for application permissions.
OBO flow fails The agent identity isn't configured for delegated permissions, or the user token doesn't include the required scopes. Verify delegated permissions are assigned. Check that the user token includes the scopes your agent needs for the OBO exchange.
400 Bad Request: Object not found (after creating blueprint) Read-after-write consistency delay. The blueprint or agent identity isn't yet available for subsequent API calls. Wait 30–60 seconds after creating the blueprint before creating agent identities or service principals. Implement retry logic with exponential backoff.
Agent ID not visible in Microsoft Entra admin center Agent identities created through the API might take a few minutes to appear in the portal. Wait and refresh. If the identity still doesn't appear, verify it was created successfully through the Graph API.

Related content

  • Last updated on