Listen to this Post
Introduction:
The rise of AI agents in platforms like Microsoft Copilot Studio has introduced a new wave of workload identities into Entra ID, often as classic service principals without centralized governance. Microsoft’s Entra Agent Identity Migration Toolkit is a powerful utility that automates the discovery, classification, and reporting of these “agentic” service principals, enabling a seamless migration to modern Microsoft Entra Agent IDs.
Learning Objectives:
- Understand the Microsoft Entra Agent Identity Migration Toolkit’s purpose, phases, and builder-specific discovery capabilities.
- Learn to set up and execute the toolkit using Docker and CLI methods, including proper Entra app registration and configuration.
- Acquire manual auditing and remediation skills using PowerShell and Graph API for scenarios where the toolkit may encounter issues.
- Apply security best practices for workload identities and anticipate future trends in AI agent identity management.
You Should Know:
1. Understanding the Toolkit and Its Components
The migration toolkit is an open-source solution designed to discover, classify, and report on agentic service principals within your Microsoft Entra ID tenant, supporting the transition from legacy app registrations to Microsoft Entra Agent IDs. The toolkit operates in four distinct phases:
| Phase | Goal | Key Output |
|-||-|
| 1 · Discover | Inventory all agent-related service principals in your tenant | A structured report with identity metadata, sign-in activity, permissions, ownership, credentials, and builder origin |
| 2 · Classify | Categorize each identity by usage level | Usage tiers: Low (cleanup candidate), Medium (review required), High (do not decommission) |
| 3 · Report | Generate CSV and interactive HTML dashboard | Sortable, filterable dashboard with Entra portal deep links and export capabilities |
| 4 · Decommission | Disable or soft-delete legacy identities (CLI only) | Legacy identities removed, with pre-deletion confirmation and 30-day soft-delete |
The toolkit automatically identifies agent origin using service principal tags. For Copilot Studio agents, it looks for tags like `AgentCreatedBy:CopilotStudio` or `power-virtual-agents-` to distinguish them from custom code app registrations.
Prerequisites:
- Python 3.10+ (for CLI mode) or Docker Desktop (for web mode)
- An Entra tenant with at least Global Reader rights (minimum)
- Delegated permissions:
Application.Read.All,Directory.Read.All,AuditLog.Read.All, andUser.Read. For decommission mode, also require `Application.ReadWrite.All`
2. Step-by-Step Setup and Execution
The toolkit offers two execution modes: a browser-based web interface and a CLI mode suitable for automation. Below is a verified step-by-step guide based on the official setup documentation.
Step 1: Clone the Repository and Switch to the Feature Branch
git clone https://github.com/microsoft/entra-agentid-samples.git cd entra-agentid-samples git checkout feature/migration-toolkit cd migration-toolkit/toolkit
Step 2: Create an App Registration in Entra
- Navigate to Entra admin center → Applications → App registrations → New registration
- Name: `Agent Identity Discovery Toolkit`
– Account types: “Accounts in this organizational directory only (Single tenant)” - Click Register
Note down the Application (client) ID and Directory (tenant) ID from the Overview page.
Step 3: Configure Authentication
In your app registration, go to Authentication:
- Click Add a platform → select Mobile and desktop applications
- Add redirect URI: `http://localhost:8080/api/auth/callback`
- Click Configure and Save
- Go to Settings and enable Allow public client flows, then click Save
No client secret is needed — the app uses PKCE (public client authentication).
Step 4: Configure Environment Variables
cp .env.example .env
Edit `.env` with your values:
AZURE_CLIENT_ID=<your-application-client-id> AZURE_TENANT_ID=<your-directory-tenant-id> REDIRECT_URI=http://localhost:8080/api/auth/callback SESSION_SECRET=<generate-a-secure-secret>
Generate a secure `SESSION_SECRET` (Mac/Linux):
openssl rand -hex 32
Step 5: Start the Toolkit with Docker Compose
docker compose up -d
Wait a few seconds, then open your browser to `http://localhost:8080`. The app will show your Tenant ID and Application (Client) ID pre-filled from your `.env` file.
Step 6: Sign In and Run a Scan
Click Sign in with Entra, complete the Microsoft sign-in flow, and you’ll be redirected back to the dashboard. Once signed in, click Start Scan. The toolkit will:
– Discover all service principals via Microsoft Graph
– Enrich with tags, permissions, and metadata
– Classify agentic service principals (Copilot Studio, Azure AI, etc.)
Results appear in the interactive dashboard when the scan completes. You can also export to CSV.
Troubleshooting the Docker Cookie Issue
As noted in the original post, some users experience a container restarting and deleting session cookies, preventing sign-in. If you encounter this:
1. Stop the container: `docker compose down`
2. Remove any orphaned volumes: `docker volume prune`
- Restart with a clean state: `docker compose up -d`
Alternatively, use the CLI mode, which is less prone to this issue:pip install -r requirements.txt python run_audit.py --tenant-id <your-tenant-id> --export-path ./reports
3. Manual Audit and Remediation Techniques
If the toolkit cannot be used due to persistent issues, you can perform manual audits using PowerShell and the Microsoft Graph API.
Auditing Service Principals with PowerShell
Install the Microsoft Graph PowerShell module:
Install-Module Microsoft.Graph -Scope CurrentUser Connect-MgGraph -Scopes "Application.Read.All", "AuditLog.Read.All"
List all service principals:
Get-MgServicePrincipal -All | Select-Object DisplayName, AppId, Tags, CreatedDateTime
Find Copilot Studio agents by filtering tags:
Get-MgServicePrincipal -All | Where-Object { $<em>.Tags -like "Copilot" -or $</em>.Tags -like "AgentCreatedBy:CopilotStudio" }
Viewing Audit Logs for Service Principal Changes
In the Entra admin center:
- Go to Monitoring & health → Audit logs
- Set Category to `ApplicationManagement`
– Filter by Activity to “Add service principal” or “Update service principal”
Manual Decommissioning
If the toolkit’s decommission mode is unavailable, you can manually disable or delete service principals:
Disable a service principal (prevents sign-in) Update-MgServicePrincipal -ServicePrincipalId <id> -AccountEnabled:$false Soft-delete (recoverable for 30 days) Remove-MgServicePrincipal -ServicePrincipalId <id> Permanently delete (after soft-delete) Remove-MgDirectoryDeletedItem -DirectoryObjectId <id>
API Security Hardening
Based on Microsoft’s Secure Future Initiative best practices, implement the following:
– Replace static credentials with managed identities and Entra Workload IDs wherever possible
– Eliminate identity lateral movement by removing legacy authentication systems
– Use Conditional Access policies to restrict service principal access based on location, risk, and device compliance
4. Security Best Practices and Future Implications
The emergence of Entra Agent IDs represents a fundamental shift in how AI agents are managed within identity frameworks. Microsoft has indicated that a formal migration tool is planned to assist organizations in converting classic agents to modern agent identities. In the meantime, auditing your tenant to understand which agents fall into which category is critical.
Key Best Practices for Workload Identities:
- Enforce least privilege: Limit the scope of access for service principals and audit permissions regularly
- Monitor risky service principals: Enable diagnostic settings for `RiskyServicePrincipals` and `ServicePrincipalRiskEvents` in Entra ID (requires Workload Identities Premium licensing)
- Never configure credentials on Microsoft services applications as Microsoft explicitly recommends against this security anti-pattern
- Prepare for Conditional Access enforcement: Microsoft is strengthening which authentication flows are subject to Conditional Access, directly impacting service principal behavior
What Undercode Say:
- Identity is the new perimeter for AI: As organizations deploy hundreds of AI agents, each with its own Entra service principal, centralizing discovery and governance becomes non-negotiable.
- The Toolkit is a lifeline: Even with its current Docker stability issues, the manual CLI mode works reliably and provides an invaluable inventory of shadow AI identities that security teams often miss.
- Manual PowerShell skills remain essential: When automated tools fail, knowing how to query Microsoft Graph directly ensures you can still perform critical security audits.
- Expect rapid evolution: Microsoft’s push toward “Agent IDs” in Copilot Studio and Azure AI Foundry signals that identity management for AI will soon match the rigor of user and device identity.
Prediction:
Within 18 months, Entra Agent IDs will become the default identity type for all Microsoft AI services, and organizations that fail to audit their legacy service principals will face significant compliance and security gaps. The migration toolkit will evolve into a fully integrated feature of the Entra admin center, with automated discovery and one-click migration. However, manual audit skills will remain critical as third-party AI agents and custom-coded agents will always operate outside the Microsoft ecosystem, requiring security teams to maintain hybrid discovery capabilities. The distinction between “user identity” and “agent identity” will blur, leading to new Zero Trust frameworks specifically designed for autonomous AI workloads.
▶️ Related Video (78% Match):
🎯Let’s Practice For Free:
IT/Security Reporter URL:
Reported By: Jan Bakker – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
