1# EMM Enable Flow
2 
3Copilot-guided step-by-step workflow for enabling Essential Machine Management on a subscription. Copilot orchestrates each step, triggering the necessary CLI commands or API calls on behalf of the user.
4 
5## Quick Reference
6 
7| Property | Value |
8| -------- | ----- |
9| Resource type | `Microsoft.ManagedOps/ManagedOps` |
10| Resource provider | `Microsoft.ManagedOps` |
11| API version | `2025-07-28-preview` |
12| Deployment scope | Subscription-level |
13 
14## Workflow Steps
15 
16### Step 1: Select Target Subscription
17 
18Ask the user which subscription to enable EMM for. Use MCP tools to list subscriptions if needed.
19 
20| MCP Tool | Purpose |
21| -------- | ------- |
22| `mcp_azure_mcp_subscription_list` | List available subscriptions |
23 
24Store the selected `subscriptionId` and `tenant` for all subsequent steps.
25 
26### Step 2: Validate User Role Assignments
27 
28Check that the current user has the 3 required roles on the target subscription. This requires two API calls: one to get the user's role assignments, and one to get all role definitions. Then compare the user's assigned permissions against the required roles.
29 
30**Step 2a: Get current user's object ID**
31 
32```bash
33az rest --method GET --url "https://graph.microsoft.com/v1.0/me" --query id -o tsv
34```
35 
36**Step 2b: Get user's role assignments on the subscription**
37 
38```text
39GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignments?api-version=2022-04-01&$filter=assignedTo('{objectId}')
40```
41 
42> 💡 **Tip:** The `assignedTo` filter is self-scoped — it allows the user to query their own role assignments without needing `Microsoft.Authorization/roleAssignments/read`. However, a 403 will still occur if the user has no role on the subscription at all.
43 
44**Step 2c: Get all role definitions on the subscription**
45 
46```text
47GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01
48```
49 
50**Step 2d: Join and check permissions**
51 
52For each role assignment, match `properties.roleDefinitionId` to the role definitions to resolve the role name and its `properties.permissions[]`. Then check whether the user's combined permissions cover all three required roles:
53 
54| Required Role | Key Permissions (actions) |
55| ------------- | ------------------------ |
56| Essential Machine Management Administrator | `Microsoft.ManagedOps/managedOps/*`, `Microsoft.Insights/dataCollectionRules/*`, `Microsoft.Monitor/accounts/*`, `Microsoft.OperationalInsights/workspaces/read`, `Microsoft.Security/pricings/*` |
57| Managed Identity Operator | `Microsoft.ManagedIdentity/userAssignedIdentities/*/read`, `Microsoft.ManagedIdentity/userAssignedIdentities/*/assign/action` |
58| Resource Policy Contributor | `Microsoft.Authorization/policyassignments/*`, `Microsoft.Authorization/policydefinitions/*`, `Microsoft.PolicyInsights/*` |
59 
60> 💡 **Tip:** If the user has **Owner** at subscription scope, they satisfy all required permissions. Check for these first as a fast path.
61 
62```text
63Check result?
64├─ All 3 roles covered → Proceed to Step 3
65├─ Owner found → All roles satisfied, proceed to Step 3
66└─ Missing roles → Inform user which roles are missing and how to assign them, then re-check
67```
68 
69### Step 3: Select or Create a User-Assigned Managed Identity (UAMI)
70 
71Ask the user to provide an existing UAMI or create a new one. The UAMI must have **Contributor** on the target subscription.
72 
73Verify the UAMI's role using the same API pattern as Step 2, but filter by the UAMI's principal ID (object ID) instead of the user's:
74 
75```text
76GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignments?api-version=2022-04-01&$filter=assignedTo('{uamiPrincipalId}')
77```
78 
79Check that at least one assignment resolves to the **Contributor** role definition.
80 
81> 💡 **Tip:** If the UAMI lacks the Contributor role, guide the user to assign it before proceeding.
82 
83Store the full UAMI resource ID: `/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>`
84 
85### Step 4: Select or Create Monitoring Workspaces
86 
87Ask the user for a **Log Analytics workspace** and an **Azure Monitor workspace**. Offer to create new ones if needed.
88 
89| Resource | CLI Command | Purpose |
90| -------- | ----------- | ------- |
91| Log Analytics workspace (list) | `az monitor log-analytics workspace list --subscription <subId> -o table` | List existing workspaces |
92| Log Analytics workspace (create) | `az monitor log-analytics workspace create --workspace-name <name> --resource-group <rg> --subscription <subId> --location <location>` | Create new workspace |
93| Azure Monitor workspace (list) | `az resource list --resource-type "Microsoft.Monitor/accounts" --subscription <subId> -o table` | List existing workspaces |
94| Azure Monitor workspace (create) | `az resource create --resource-type "Microsoft.Monitor/accounts" --name <name> --resource-group <rg> --subscription <subId> --location <location> --properties "{}"` | Create new workspace |
95 
96> ⚠️ **Warning:** If workspaces are in a **different subscription** than the target:
97> - Register `Microsoft.ManagedOps` RP in the workspace subscription
98> - User needs **EMM Administrator** role on the workspace resource group
99> - UAMI needs **Contributor** on the workspace resource group
100 
101Store both workspace resource IDs.
102 
103### Step 5: Configure Security Options
104 
105Ask the user about optional security add-ons.
106 
107| Feature | Default | Cost |
108| ------- | ------- | ---- |
109| Foundational CSPM | Always enabled | Free |
110| Defender CSPM | Disabled | Paid |
111| Defender for Cloud | Disabled | Paid |
112 
113Store user selections as `enabled` or `disabled`.
114 
115### Step 6: Register Resource Providers
116 
117Register required RPs on the target subscription before deployment.
118 
119```bash
120az provider register --namespace Microsoft.ManagedOps --subscription <subscriptionId>
121az provider register --namespace Microsoft.OperationsManagement --subscription <subscriptionId>
122az provider register --namespace Microsoft.PolicyInsights --subscription <subscriptionId>
123az provider register --namespace Microsoft.Insights --subscription <subscriptionId>
124az provider register --namespace Microsoft.OperationalInsights --subscription <subscriptionId>
125az provider register --namespace Microsoft.Monitor --subscription <subscriptionId>
126az provider register --namespace Microsoft.ManagedIdentity --subscription <subscriptionId>
127az provider register --namespace Microsoft.Security --subscription <subscriptionId>
128```
129 
130> 💡 **Tip:** RP registration is idempotent — safe to run even if already registered.
131 
132### Step 7: Deploy EMM via ARM API
133 
134Submit the PUT request to enable EMM on the subscription.
135 
136```text
137PUT /subscriptions/{subscriptionId}/providers/Microsoft.ManagedOps/managedOps/default?api-version=2025-07-28-preview
138```
139 
140Request body:
141 
142```json
143{
144  "properties": {
145    "desiredConfiguration": {
146      "defenderCspm": "<enabled|disabled>",
147      "defenderForServers": "<enabled|disabled>",
148      "changeTrackingAndInventory": {
149        "logAnalyticsWorkspaceId": "<log-analytics-workspace-resource-id>"
150      },
151      "userAssignedManagedIdentityId": "<uami-resource-id>",
152      "azureMonitorInsights": {
153        "azureMonitorWorkspaceId": "<azure-monitor-workspace-resource-id>"
154      }
155    }
156  }
157}
158```
159 
160Populate the request body with the values collected in previous steps.
161 
162### Step 8: Verify Enrollment
163 
164After deployment completes, confirm the subscription is enrolled.
165 
166```text
167GET /subscriptions/{subscriptionId}/providers/Microsoft.ManagedOps/managedOps/default?api-version=2025-07-28-preview
168```
169 
170```text
171Deployment status?
172├─ Succeeded → Report success to user. All existing VMs will be enrolled via policy remediation.
173├─ In progress → Wait and re-check after a short interval.
174└─ Failed → Read error details and route to Error Handling in the parent workflow.
175```
176 
177## Disable EMM (Offboard)
178 
179To disable EMM for a subscription:
180 
181```text
182DELETE /subscriptions/{subscriptionId}/providers/Microsoft.ManagedOps/managedOps/default?api-version=2025-07-28-preview
183```
184 
185> ⚠️ **Warning:** Disabling reverts pricing to standard per-service rates, which may increase costs. Existing VM configurations are not removed.
186 
187## Error Handling
188 
189| Error | Cause | Remediation |
190| ----- | ----- | ----------- |
191| 403 on role check | User has no RBAC role assignment on the subscription (the `assignedTo` filter is self-scoped and does not require `roleAssignments/read`, but the user must have at least one role on the subscription) | Inform user they lack Owner or Contributor role on this subscription and cannot proceed with EMM enrollment |
192| Missing required roles | User missing EMM Administrator, Managed Identity Operator, or Resource Policy Contributor | Guide user to assign missing roles, then re-validate |
193| UAMI lacks Contributor | Managed identity missing Contributor role | Assign Contributor to the UAMI at subscription scope |
194| RP registration failed | Insufficient permissions to register providers | User needs Contributor or Owner on the subscription |
195| PUT deployment fails | ARM validation error | Check error details; verify all prerequisites met |
196| Cross-subscription error | Workspace in different sub without RP/role setup | Register `Microsoft.ManagedOps` in workspace sub; assign roles on workspace RG |
197