manage_azure_ad_roles
Assign, remove, or review Azure AD administrative role permissions for users, groups, and service principals to control access in Microsoft 365 environments.
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)Full handler function implementing manage_azure_ad_roles tool logic using Microsoft Graph API for listing roles/assignments, assigning roles, and removing assignments.// 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)Tool registration in MCP server, linking to handleAzureAdRoles handler with schema and annotations.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 input parameters for the manage_azure_ad_roles tool.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/types.ts:126-132 (schema)TypeScript interface defining the arguments structure for the handler.export interface AzureAdRoleArgs { action: 'list_roles' | 'list_role_assignments' | 'assign_role' | 'remove_role_assignment'; roleId?: string; principalId?: string; assignmentId?: string; filter?: string; }
- src/tool-metadata.ts:69-72 (helper)Metadata providing description, title, and annotations (readOnlyHint, destructiveHint, etc.) for the tool.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 }