manage_azure_ad_roles
Assign, remove, and manage Azure Active Directory administrative roles and permissions for users, groups, and service principals.
Instructions
Manage Azure AD administrative roles including role assignments, custom roles, and privilege escalation controls.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Azure AD role management action | |
| roleId | No | ID of the directory role | |
| principalId | No | ID of the principal (user, group, SP) | |
| assignmentId | No | ID of the role assignment to remove | |
| filter | No | OData filter string |
Implementation Reference
- src/handlers.ts:338-394 (handler)The handler function implementing the core logic for the manage_azure_ad_roles tool. Supports listing roles and assignments, assigning roles to principals, and removing role assignments using Microsoft Graph API endpoints.// Azure AD Roles Handler export async function handleAzureAdRoles( graphClient: Client, args: AzureAdRoleArgs ): Promise<{ content: { type: string; text: string }[] }> { let apiPath = ''; let result: any; switch (args.action) { case 'list_roles': apiPath = '/directoryRoles'; if (args.filter) { apiPath += `?$filter=${encodeURIComponent(args.filter)}`; } result = await graphClient.api(apiPath).get(); break; case 'list_role_assignments': // Note: Listing all role assignments requires Directory.Read.All // Filtering by principal requires RoleManagement.Read.Directory apiPath = '/roleManagement/directory/roleAssignments'; if (args.filter) { // Example filter: $filter=principalId eq '{principalId}' apiPath += `?$filter=${encodeURIComponent(args.filter)}`; } result = await graphClient.api(apiPath).get(); break; case 'assign_role': if (!args.roleId || !args.principalId) { throw new McpError(ErrorCode.InvalidParams, 'roleId and principalId are required for assign_role'); } apiPath = '/roleManagement/directory/roleAssignments'; const assignmentPayload = { '@odata.type': '#microsoft.graph.unifiedRoleAssignment', roleDefinitionId: args.roleId, principalId: args.principalId, directoryScopeId: '/', // Assign at tenant scope }; result = await graphClient.api(apiPath).post(assignmentPayload); break; case 'remove_role_assignment': if (!args.assignmentId) { throw new McpError(ErrorCode.InvalidParams, 'assignmentId is required for remove_role_assignment'); } apiPath = `/roleManagement/directory/roleAssignments/${args.assignmentId}`; await graphClient.api(apiPath).delete(); result = { message: 'Role assignment removed successfully' }; break; default: throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`); } return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; }
- src/server.ts:520-539 (registration)MCP server registration of the manage_azure_ad_roles tool, specifying description, input schema, annotations, and linking to the handleAzureAdRoles handler function.this.server.tool( "manage_azure_ad_roles", "Manage Azure AD administrative roles including role assignments, custom roles, and privilege escalation controls.", azureAdRoleSchema.shape, {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false}, wrapToolHandler(async (args: AzureAdRoleArgs) => { // Validate credentials only when tool is executed (lazy loading) this.validateCredentials(); try { return await handleAzureAdRoles(this.getGraphClient(), args); } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Error executing tool: ${error instanceof Error ? error.message : 'Unknown error'}` ); } })
- src/tool-definitions.ts:128-134 (schema)Zod schema defining the input parameters for the manage_azure_ad_roles tool, including supported actions and parameters like roleId, principalId, etc.export const azureAdRoleSchema = z.object({ action: z.enum(['list_roles', 'list_role_assignments', 'assign_role', 'remove_role_assignment']).describe('Azure AD role management action'), roleId: z.string().optional().describe('ID of the directory role'), principalId: z.string().optional().describe('ID of the principal (user, group, SP)'), assignmentId: z.string().optional().describe('ID of the role assignment to remove'), filter: z.string().optional().describe('OData filter string'), });
- src/tool-metadata.ts:69-72 (schema)Tool metadata including description, title, and annotations (readOnlyHint, destructiveHint, etc.) used during MCP server registration.manage_azure_ad_roles: { description: "Manage Azure AD administrative roles including role assignments, custom roles, and privilege escalation controls.", title: "Azure AD Role Manager", annotations: { title: "Azure AD Role Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }