How to use Update-MgUser with Microsoft Graph PowerShell

Using PowerShell to make simple user changes in Microsoft 365 can be a lot faster and more efficient than using the Admin console if you are familiar with the commands. It will also help greatly if you need to perform large-scale changes for multiple users by automating a repetitive task.

In this tutorial, I will show you how you can use the Update-MgUser cmdlet in Microsoft Graph PowerShell to make changes to user accounts in Microsoft 365.

Page Contents

About the Update-MgUser cmdlet

The Update-MgUser cmdlet belongs to the Microsoft.Graph.Users module, part of the Microsoft Graph PowerShell SDK. It is used to change the configuration of user accounts in Microsoft 365.

Behind the scenes, when you use the Update-MgUser cmdlet, the following URL is called to the Microsoft Graph API with the PATCH request method:

https://graph.microsoft.com/v1.0/users/{id}

Permissions required for Update-MgUser

The minimum level of permissions you need to run this cmdlet and successfully update a user is the User.ReadWrite.All permission. However, there are other permission scopes which contain the permission to update users, these are:

User.ManageIdentities.All
Directory.ReadWrite.All

For example, you can see from the below image that I have created a new Microsoft Graph PowerShell session with only the User.ManageIdentities.All permission scope. With this, I could update the DisplayName field of a user in my tenant.

Change users UPN with Microsoft Graph PowerShell

Changing a user’s UPN (or User Principal Name) in Microsoft is quick and easy using Microsoft Graph PowerShell. You can simply use the Update-MgUser cmdlet with the -UserPrincipalName parameter like in the following example:

Update-MgUser -UserId [email protected] '
-UserPrincipalName "[email protected]"

It is still important that you know the impact of modifying a user’s UPN in Microsoft 365 as it could adversely affect their productivity if executing this command in a poorly planned manner.

You should know that when changing the domain portion of a user UPN, you must specify a domain that is active and accepted by your tenant. This could be a custom domain, such as ourcloudnetwork.com or the default (or ‘fallback’) domain, in the format of company.onmicrosoft.com.

How to change the UPN for multiple users

The Update-MgUser cmdlet and examples we have used above can be adapted and applied to multiple users within a single command, which help simplifies changes and keeps the changes consistent and void of human error.

To do this, we will use a simple ForEach loop in PowerShell.

Start by collecting your users based on a condition. You may want to change all users in your tenant, so just using Get-MgUser -All may be sufficient. For my example, I am going to store all users in an array and then change the UPN to have a different domain. Below I am specifying all users that have a specific domain in their UPN, which I will then change.

$users = Get-MgUser | Where UserPrincipalName -match ourcloudnetwork.co.uk

If you want to learn more about the Get-MgUser cmdlet to use more advanced queries, check out my guide on How To Use Get-MgUser with Microsoft Graph PowerShell.

We can type the $users variable directly into our PowerShell session to confirm that all of our desired users have been successfully stored. If also want to quickly specify how many items (users) there are in the array, type $users.count.

To loop through each user and update the UserPrincipalName, we can use the following example.

$newdomain = "x7kxf.onmicrosoft.com" ##Add your accepted domain
ForEach ($user in $users) {
    $string = $null
    $userupn = $null
    $string = ($user.UserPrincipalName)
    $regex = "(\S*)(\.(\S*))?@(\S*)"
    $string -match $regex
    $userupn = $matches[1] + "@" + $newupn
    Update-MgUser -UserId $user.UserPrincipalName -UserPrincipalName $userupn
    Write-host "UPN for $($user.DisplayName) has been updated to $userupn"
}

If have used regular expressions to break apart the UPN into 2 sections, the prefix and the domain. You can use the above example and modify it to your needs.

How to change other user properties with Microsoft Graph PowerShell

We have seen above that there are many available parameters for the Update-MgUser cmdlet, all with different names and performing different actions. Below is some common examples of user changes you may encounter in day-to-day activities.

Update a user’s About me.

Update-MgUser -UserId [email protected] -AboutMe "String"

Update a user’s City.

Update-MgUser -UserId [email protected] -City "String"

Update a user’s Country.

Update-MgUser -UserId [email protected] -Country "String"

Update a user’s Department.

Update-MgUser -UserId [email protected] -Department "String"

Update a user’s Display Name.

Update-MgUser -UserId [email protected] -DisplayName "String"

Update a user’s Job Title.

Update-MgUser -UserId [email protected] -JobTitle "String"

Update a user’s Primary SMTP Address. This field must contain one of the accepted domains in your tenant.

Update-MgUser -UserId [email protected] -Mail "String"

How to change multiple user properties at once for a single user

If you need to update multiple properties for a single user at once in the same command, instead of having multiple lines of code, you can define multiple parameters in the same command for simplicity. For example, if a user has had a name change, such as getting married, to their DisplayName, UpdatePrincipalName and Mail address in the same command, you can use the following:

Update-MgUser -UserId [email protected] '
-DisplayName "Daniel Bradley" `
-UserPrincipalName "[email protected]" `
-Mail "[email protected]"