Edit

Share via

Assign admin roles to Microsoft 365 user accounts with PowerShell

  • Article

This article applies to both Microsoft 365 Enterprise and Office 365 Enterprise.

You can easily assign roles to user accounts by using PowerShell for Microsoft 365.

Note

Learn how to assign admin roles to user accounts with the Microsoft 365 admin center.

For a list of additional resources, see Manage users and groups.

Assign roles to user accounts using Microsoft Graph PowerShell

Note

The Azure Active Directory module is being replaced by the Microsoft Graph PowerShell SDK. You can use the Microsoft Graph PowerShell SDK to access all Microsoft Graph APIs. For more information, see Get started with the Microsoft Graph PowerShell SDK.

First, use a Microsoft Entra DC admin or Cloud Application Admin account to connect to your Microsoft 365 tenant. The cmdlets in this article require the permission scope RoleManagement.ReadWrite.Directory or one of the other permissions listed in the 'List subscribedSkus' Graph API reference page. Some commands in this article may require different permission scopes, in which case this will be noted in the relevant section.

PowerShell 
Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory"

For more information, see About admin roles.

Next, identify the sign-in name of the user account that you want to add to a role (example: fredsm@contoso.com). This is also known as the user principal name (UPN).

Next, determine the name of the role. See Microsoft Entra built-in roles.

Note

Some role names are different for Azure Active Directory (Azure AD) PowerShell. For example, the SharePoint Administrator role in the Microsoft 365 admin center is SharePoint Service Administrator in Azure AD PowerShell.

Next, fill in the user UPN and role names and run these commands:

PowerShell 
$userUPN="<user UPN>"
$roleName="<role name>"
$role = Get-MgDirectoryRole | Where-Object {$_.displayName -eq $roleName}
if ($role -eq $null) {
    $roleTemplate = (Get-MgDirectoryRoleTemplate | Where-Object {$_.displayName -eq $roleName}).id
    New-MgDirectoryRole -DisplayName $roleName -RoleTemplateId $roleTemplate
    $role = Get-MgDirectoryRole | Where-Object {$_.displayName -eq $roleName}
}
$userId = (Get-MgUser -Filter "userPrincipalName eq '$userUPN'").Id
$newRoleMember =@{
    "@odata.id"= "https://graph.microsoft.com/v1.0/users/$userId"
    }
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $role.Id -BodyParameter $newRoleMember

Here's an example of a completed command set that assigns the Exchange Administrator role to the adelev@contoso.com account:

PowerShell 
$userUPN="adelev@contoso.com"
$roleName="Exchange Administrator"
$role = Get-MgDirectoryRole | Where-Object {$_.displayName -eq $roleName}
if ($role -eq $null) {
    $roleTemplate = (Get-MgDirectoryRoleTemplate | Where-Object {$_.displayName -eq $roleName}).id
    New-MgDirectoryRole -DisplayName $roleName -RoleTemplateId $roleTemplate
    $role = Get-MgDirectoryRole | Where-Object {$_.displayName -eq $roleName}
}
$userId = (Get-MgUser -Filter "userPrincipalName eq '$userUPN'").Id
$newRoleMember =@{
    "@odata.id"= "https://graph.microsoft.com/v1.0/users/$userId"
    }
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $role.Id -BodyParameter $newRoleMember

To display the list of user IDs for a specific admin role, use these commands.

PowerShell 
$roleName="<role name>"
Connect-MgGraph -Scopes "Directory.Read.All"
Get-MgDirectoryRole | Where-Object { $_.DisplayName -eq $roleName } | ForEach-Object { Get-MgDirectoryRoleMember -DirectoryRoleId $_.Id }

See also