Update-MgUser: How to Update Microsoft 365 User Details

This guide explores how to use Update-MgUser cmdlet in Graph PowerShell to modify user attributes in your Microsoft 365 tenant. Learn how to update properties such as display name, phone number, and department, and explore examples for both single and bulk user updates.

Updating user information in Microsoft 365 is a common administrative task. The Update-MgUser cmdlet in the Microsoft Graph PowerShell module provides a powerful way to update user properties. This article will cover the Update-MgUser cmdlet basics like the cmdlet prerequisites, cmdlet syntax with parameter explanations, various usage examples, helpful tips, common errors involved with solutions.

Prerequisites

• Microsoft Graph PowerShell Module: Install the module if you haven't already.

  Install-Module -Name Microsoft.Graph -Scope CurrentUser

• Required Permissions: Ensure your account has the necessary permissions to update user information. The minimum required permissions are User.ReadWrite.All.
• Authentication: Connect to Microsoft Graph using the following command:

  Connect-MgGraph -Scopes "User.ReadWrite.All"

Cmdlet Syntax

Update-MgUser -UserId <String> [-AccountEnabled <Boolean>] [-DisplayName <String>] [-JobTitle <String>] [-MobilePhone <String>] [-OfficeLocation <String>] [-OtherMails <String[]>] [-PreferredLanguage <String>] [-Surname <String>] [-UserPrincipalName <String>] []

• -UserId: The unique identifier of the user to update. This can be the user's Id, UserPrincipalName, or Email.
• -AccountEnabled: Specifies whether the user's account is enabled or disabled.
• -DisplayName: The user's display name.
• -JobTitle: The user's job title.
• -MobilePhone: The user's mobile phone number.
• -OfficeLocation: The user's office location.
• -OtherMails: Additional email addresses for the user.
• -PreferredLanguage: The user's preferred language.
• -Surname: The user's last name.
• -UserPrincipalName: The user's principal name (user's sign-in name).

Usage Examples

Example 1: Update a User's Display Name and Job Title

Update-MgUser -UserId "john.doe@contoso.com" -DisplayName "Johnathan Doe" -JobTitle "Senior Developer"

Example 2: Enable a User's Account

Update-MgUser -UserId "jane.smith@contoso.com" -AccountEnabled $true

Example 3: Update Multiple User Properties

Update-MgUser -UserId "alex.wang@contoso.com" -MobilePhone "+1 555 555 5555" -OfficeLocation "Building 4" -PreferredLanguage "en-US"

Example 4: Add Additional Email Address

Update-MgUser -UserId "mary.jones@contoso.com" -OtherMails @("mary.jones@otherdomain.com")

Example 5: Update User Principal Name

Update-MgUser -UserId "old.username@contoso.com" -UserPrincipalName "new.username@contoso.com"

Example 6: Update the City and Country of a User

Useful for updating physical location information for directory accuracy or compliance.

Update-MgUser -UserId "alex.wilson@yourdomain.com" -BodyParameter @{
    city = "Seattle"
    country = "United States"
}

Updating Microsoft 365 User Using Admin Center

1. Login into Microsoft 365 Admin Center
2. Select Users >> Active Users page.

3. Select User to be updated >> go to Accounts tab >> Update the required details >> Save the User .

Cmdlet Tips

• Batch Updates: For updating multiple users, consider using a loop to process a list of users from a CSV file.
• Backup Data: Always back up current user data before making bulk updates to avoid accidental data loss.
• Error Handling: Use try-catch blocks to handle potential errors gracefully in your scripts.
• Use -WhatIf Alternative for Testing Logic While Update-MgUser doesn't support -WhatIf, you can preview changes by first retrieving the user's current properties with Get-MgUser -UserId and comparing the intended values before updating. This minimizes mistakes during bulk updates.

Use Cases

1. Updating User Information Post-Onboarding
• Scenario: After new employees have been onboarded, there may be a need to update their profile information, such as adding job titles, departments, or mobile phone numbers.
• Implementation: Use Update-MgUser to quickly update these details for individual users.
• Benefit: Ensures that employee profiles are kept up-to-date with accurate information, which is crucial for internal communications and organizational structure.


2. Enforcing Naming Conventions:
• Scenario: Organizations may enforce specific naming conventions for UserPrincipalName, DisplayName, or MailNickname to maintain consistency across the directory.
• Implementation: Use Update-MgUser to modify these properties in bulk, aligning user profiles with the organization's naming standards.
• Benefit: Helps in maintaining a professional and consistent directory, making it easier to manage and search for users.


3. Bulk Updating User Information
• Scenario: HR or IT departments need to make changes to multiple users’ profiles, such as updating job titles after a company-wide reorganization or changing office locations.
• Implementation: Use a CSV file to manage bulk updates, where each row represents a user and their updated properties.
• Benefit: Streamlines the process of making large-scale changes, saving time and reducing the potential for errors.



CSV File Example:

UserPrincipalName,JobTitle,Department,OfficeLocation
johndoe@domain.com,Manager,Sales,New York
janedoe@domain.com,Engineer,IT,San Francisco




    $users = Import-Csv -Path "C:\Path\To\Users.csv"
        foreach ($user in $users) {
            $userParams = @{
            JobTitle = $user.JobTitle
            Department = $user.Department
            OfficeLocation = $user.OfficeLocation
        }
            Update-MgUser -UserId $user.UserPrincipalName -BodyParameter $userParams
        }

Common Errors and Solutions

Connect-MgGraph -Scopes "User.ReadWrite.All"

Frequently Asked Questions

What is Update-MgUser used for?

Update-MgUser is a Microsoft Graph PowerShell cmdlet used to modify user attributes in a Microsoft 365 tenant. It allows updating various properties, such as display name, department, job title, and phone numbers.

How can I update a user’s display name using Update-MgUser?

To update a user’s display name, use the following script:

    Update-MgUser -UserId "<UserPrincipalName>" -BodyParameter @{ "displayName" = "New Display Name" }

Can I update multiple users at once using Update-MgUser?

Yes, bulk updates can be performed using a CSV file. Prepare the file with the following format:

    UserPrincipalName,DisplayName,Department
    user1@domain.com,New Display Name 1,Sales
    user2@domain.com,New Display Name 2,Marketing

Use this script to update user properties:

    $Users = Import-Csv -Path "C:\Path\To\File.csv"
    foreach ($User in $Users) {
    $Body = @{
        "displayName" = $User.DisplayName
        "department" = $User.Department
    }
    Update-MgUser -UserId $User.UserPrincipalName -BodyParameter $Body
    }

Can I update multiple properties of a user simultaneously using Update-MgUser?

You can update multiple user properties in a single call by passing them together in the -BodyParameter hashtable. For example:

$params = @{
    displayName     = "Alex Morgan"
    jobTitle        = "Senior Analyst"
    department      = "Finance"
    officeLocation  = "Building 5"
}
Update-MgUser -UserId "alex.morgan@domain.com" -BodyParameter $params

What should I do if I get a "Request_BadRequest" error while using Update-MgUser?

This error usually means you're trying to update an unsupported or improperly formatted property.

Double-check

• That the property name is correct (e.g., use jobTitle not JobTitle)
• That the value is in the correct format (e.g., don't pass numbers in a string-only field)
• You're not trying to update a read-only property like userPrincipalName without special permissions.

try {
    Update-MgUser -UserId "user@domain.com" -BodyParameter $params
} catch {
    $_.Exception.Message
}                   

Conclusion

The Update-MgUser cmdlet is a versatile tool for updating user information in Microsoft 365. By understanding its parameters and usage, you can efficiently manage user properties. Remember to handle errors gracefully and verify your input data to avoid common pitfalls. With these practices, you can ensure smooth and effective updates to your organization's user information.

Suggested Reading

• Using New-MgUser in Graph PowerShell
• Using Get-MgUser in Graph PowerShell
• Using Remove-MgUser in Graph PowerShell
• Using Get-MgUserLicenseDetail in Graph PowerShell
• Using Set-MgUserLicense to Remove User License in Graph PowerShell