ITOps AI - Microsoft Entra Prerequisites

---

Executive Summary

This document outlines the mandatory Microsoft Entra API permissions, directory roles, and security configurations required for the Beak ITOps AI agent to execute IT operations tasks including user lifecycle management, group administration, Teams channel provisioning, and license management.

The implementation follows the principle of least privilege using service principal authentication with client secret based credentials. All sensitive operations require explicit role assignments in Microsoft Entra ID combined with corresponding Microsoft Graph API permissions.

---

Part 1: Service Principal Setup

1.1 App Registration Prerequisites

Before configuring permissions, ensure the following prerequisites are met:

Requirement	Details
Microsoft Entra Tenant	Active subscription with admin access
Global Administrator or Application Administrator	Required to register app and assign roles
API Access Enabled	Microsoft Graph API must be available in your tenant
Audit Logging	Enable for service principal activities (Microsoft Purview/Audit logs)

1.2 Create App Registration

Location: Microsoft Entra admin center → App registrations → New registration

Configuration:

• Name: Beak-ITOps-Agent (or organization-specific naming)
• Supported account types: Accounts in this organizational directory only (single tenant)
• Redirect URI: Not required for service principal (daemon/background service)
• Authentication method: Client secret

Generate Credentials:

• Method: Generate client secret with minimum 24-month expiration
• Security: Store credentials securely; never commit to version control

---

Part 2: API Permissions

2.1 Required Microsoft Graph API Permissions

All permissions below must be added as Application permissions (not delegated). Admin consent is required.

User Management Permissions

Permission	API Scope	Purpose	Least Privileged
User.ReadWrite.All	Application	Create, update, delete, disable/enable users; reset passwords	✓
User.ManageIdentities.All	Application	Manage user identities and account unlock operations	✓
Directory.AccessAsUser.All	Delegated*	Required for delete operations on privileged admin accounts	⚠

Note: Directory.AccessAsUser.All is typically delegated, but when used with app-only context, requires service principal assigned Privileged Role Administrator or higher.

Group Management Permissions

Permission	API Scope	Purpose	Least Privileged
GroupMember.ReadWrite.All	Application	Add/remove users from groups; manage group membership	✓
Group.ReadWrite.All	Application	Modify group properties and manage group lifecycle	✓
Group.Create	Application	Create new security groups and distribution lists	✓
Directory.ReadWrite.All	Application	Manage directory objects; create groups with advanced properties	⚠

Teams & Channels Permissions

Permission	API Scope	Purpose	Least Privileged
Channel.Create	Application	Create channels in any team	✓
Channel.Manage.All	Application	Manage channel settings and update channel information	✓
TeamMember.ReadWrite.All	Application	Add/remove members from Teams and channels	✓
Team.ReadWrite.All	Application	Read and manage team properties (if needed)	Optional

Licensing Permissions

Permission	API Scope	Purpose	Least Privileged
User.ReadWrite.All	Application	Assign/remove Microsoft licenses from users	(Included above)
Organization.Read.All	Application	Read available subscriptions and SKUs in tenant	✓

2.2 Permission Grant Steps

In Microsoft Entra admin center:

1. Navigate to App registrations → Select your app → API permissions
2. Click + Add a permission → Select Microsoft Graph → Application permissions
3. Search for and select each permission from Section 2.1
4. Click Add permissions
5. Click Grant admin consent for [Tenant Name] (requires Global Administrator)
6. Verify all permissions show Status: Granted with green checkmark

2.3 Permission Validation

Run this PowerShell command to verify granted permissions:

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "AppRoleAssignment.ReadWrite.All"

# Get service principal and display permissions
$servicePrincipal = Get-MgServicePrincipal -Filter "displayName eq 'Beak-ITOps-Agent'"
$servicePrincipal.AppRoles | Select-Object DisplayName, IsEnabled | Format-Table

# Alternative: Check via app object
Get-MgApplication -Filter "displayName eq 'Beak-ITOps-Agent'" | 
  Select-Object -ExpandProperty RequiredResourceAccess

---

Part 3: Microsoft Entra Directory Roles

3.1 Required Role Assignments

The service principal must be assigned the following Microsoft Entra directory roles at the tenant root scope to execute sensitive operations.

Primary Role: User Administrator

Role ID: fe930be7-5e62-47db-91af-98c3a49a38b1

Permissions Granted:

• Create, update, disable, and delete user accounts
• Reset user passwords (including setting temporary passwords)
• Force password change on next sign-in
• Assign and remove Microsoft 365 licenses
• Create and manage security and distribution groups
• Add/remove group members
• Restore deleted users
• Manage user basic properties (phone, address, department, etc.)

Limitations:

• Cannot reset passwords for Global Administrators or other User Administrators
• Cannot modify MFA settings (requires Privileged Authentication Administrator)
• Cannot manage Azure resource access (Azure RBAC)

Secondary Role: Privileged Authentication Administrator

Role ID: 7be44c8a-adaf-4e2a-84d6-ab2649e08a13

Permissions Granted:

• View, set, and reset authentication methods for ANY user (including admins)
• Force password change on next login for privileged accounts
• Manage authentication methods (passwords, phone, FIDO2, passwordless sign-in)
• Reset MFA settings for users
• Unlock accounts (via authentication method reset)

Use Case: Required when AI agent needs to reset passwords for users with administrator roles or manage MFA for high-privilege accounts.

Scope: Assign at tenant root or specific administrative unit for scoped delegation.

3.2 Role Assignment Steps

Option A: Using Microsoft Entra Admin Center (GUI)

1. Navigate to Entra ID → Roles and admins → All roles
2. Search and select User Administrator
3. Click + Add assignments
4. Search for your service principal: Beak-ITOps-Agent
5. Select the service principal and click Next
6. Review and click Assign
7. Repeat for Privileged Authentication Administrator role

Option B: Using PowerShell

# Install module (if needed)
Install-Module Microsoft.Graph.Identity.DirectoryManagement

# Connect with admin consent
Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory"

# Get service principal
$servicePrincipal = Get-MgServicePrincipal -Filter "displayName eq 'Beak-ITOps-Agent'"
$servicePrincipalId = $servicePrincipal.Id

# Get role definitions
$userAdminRole = Get-MgRoleManagementDirectoryRoleDefinition -Filter "displayName eq 'User Administrator'"
$authAdminRole = Get-MgRoleManagementDirectoryRoleDefinition -Filter "displayName eq 'Privileged Authentication Administrator'"

# Assign roles (requires tenant root scope)
New-MgRoleManagementDirectoryRoleAssignment -RoleDefinitionId $userAdminRole.Id -PrincipalId $servicePrincipalId -DirectoryScopeId "/"
New-MgRoleManagementDirectoryRoleAssignment -RoleDefinitionId $authAdminRole.Id -PrincipalId $servicePrincipalId -DirectoryScopeId "/"

# Verify assignments
Get-MgRoleManagementDirectoryRoleAssignment -Filter "principalId eq '$servicePrincipalId'"

3.3 Role Scope Considerations

Scope	Use Case	Security Impact
Tenant root (/)	Manage users across entire organization	Highest privilege; use PIM for time-limited access
Administrative Unit	Restrict to specific department or group	Recommended for delegated access; limits blast radius
Resource Group	(Not applicable for Entra ID)	N/A

Recommendation: Start with administrative unit scope if your organization structure supports it; escalate to tenant scope only if operational requirements mandate it.

---

Part 4: Feature-Specific Requirements

4.1 User Account Unlock

Task: User Account Unlock

Required Permissions:

• API: User.ManageIdentities.All
• Role: User Administrator OR Privileged Authentication Administrator

4.2 Reset User Password

Task: Reset User Password / Force Password Change on Next Login

Required Permissions:

• API: User.ReadWrite.All, User.ManageIdentities.All
• Role: User Administrator or Privileged Authentication Administrator

4.3 Create New User

Task: Create New User Account

Required Permissions:

• API: User.ReadWrite.All
• Role: User Administrator

4.4 Disable / Delete User Account

Task: Disable or Delete User Account

Required Permissions:

• API: User.ReadWrite.All
• Role: User Administrator or Privileged Authentication Administrator
• Special Note: Deleting users with admin roles requires higher privilege

4.5 Add / Remove User from Group

Task: Add User to Group / Remove User from Group / Reset Group Membership

Required Permissions:

• API: GroupMember.ReadWrite.All, Group.ReadWrite.All
• Role: User Administrator or Groups Administrator

4.6 Create Security Group

Task: Create New Security Group

Required Permissions:

• API: Group.Create, Group.ReadWrite.All
• Role: User Administrator or Groups Administrator

4.7 Create Distribution List

Task: Create New Distribution List (Mail-Enabled Group)

Required Permissions:

• API: Group.Create, Group.ReadWrite.All
• Role: User Administrator, Groups Administrator, or Exchange Administrator

4.8 Create Teams Channels

Task: Create MS Teams Channels / Add Members to Channels

Required Permissions:

• API: Channel.Create, Channel.Manage.All, TeamMember.ReadWrite.All
• Role: Teams Administrator (optional; Beak agent can operate with Graph permissions alone)

4.9 Assign Microsoft Licenses

Task: Assign Microsoft Licenses to User

Required Permissions:

• API: User.ReadWrite.All, Organization.Read.All
• Role: User Administrator or License Administrator

Prerequisites:

• User must have usageLocation set (country/region)
• License SKU must be available in tenant
• No conflicting licenses (e.g., Office 365 E5 + E3)

4.10 Manage Calendar Access

Task: Centrally manage user calendar access and delegation

Required Permissions:

• API: Calendars.ReadWrite, Calendars.ReadWrite.Shared
• Role (Entra ID / Exchange Online):
  • Exchange Administrator or
  • Application RBAC role scoped to mailbox calendars (e.g., custom role based on Mailbox Recipient Permissions)

Prerequisites:

• Target mailboxes are licensed for Exchange Online and have an Exchange mailbox provisioned
• Service principal is granted Microsoft Graph application permissions with admin consent for:
  • Calendars.ReadWrite
  • Calendars.ReadWrite.Shared
• (Recommended) Application access is limited to specific mailboxes using Exchange Application RBAC and/or Application Access Policies for least privilege