Edit

Configure Microsoft 365 user account properties with PowerShell

  • Article

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

You can use the Microsoft 365 admin center to configure properties for the user accounts of your Microsoft 365 tenant. In PowerShell, you can also do this, plus some other things you can't do in the admin center.

Configure Microsoft 365 user account properties with 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, Cloud Application Admin, or Global admin account to connect to your Microsoft 365 tenant. The cmdlets in this article require the permission scope User.ReadWrite.All 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.

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

Change properties for a specific user account

You identify the account with the -ObjectID parameter and set or change specific properties by using additional parameters. Here's a list of the most common parameters:

  • -Department "<department name>"

  • -DisplayName "<full user name>"

  • -FacsimilieTelephoneNumber "<fax number>"

  • -GivenName "<user first name>"

  • -Surname "<user last name>"

  • -Mobile "<mobile phone number>"

  • -JobTitle "<job title>"

  • -PreferredLanguage "<language>"

  • -StreetAddress "<street address>"

  • -City "<city name>"

  • -State "<state name>"

  • -PostalCode "<postal code>"

  • -Country "<country name>"

  • -TelephoneNumber "<office phone number>"

  • -UsageLocation "<2-character country or region code>"

    This is the ISO 3166-1 alpha-2 (A2) two-letter country or region code.

Note

Before you can assign licenses to a user account, you must assign a usage location.

To display the User Principal Name (UPN) for your user accounts, run the following command.

Get-MgUser -All | Sort-Object UserPrincipalName | Select-Object UserPrincipalName | More

This command instructs PowerShell to:

  1. Get all the information on the user accounts (Get-MgUser) and send it to the next command (|).

  2. Sort the list of UPNs alphabetically (Sort UserPrincipalName) and send it to the next command (|).

  3. Display just the UPN property for each account (Select UserPrincipalName).

  4. Display them one screen at a time (More).

To display the UPN for an account based on its display name (first and last name), run the following commands. Fill in the $userName variable, and remove the < and > characters:

$userName="<Display name>"
Write-Host (Get-MgUser -All | where {$_.DisplayName -eq $userName}).UserPrincipalName

This example displays the UPN for the user account that has the display name Caleb Sills.

$userName="Caleb Sills"
Write-Host (Get-MgUser -All | where {$_.DisplayName -eq $userName}).UserPrincipalName

By using a $upn variable, you can make changes to individual accounts based on their display name. Here's an example that sets Belinda Newman's usage location to France. But it specifies her display name rather than her UPN:

$userName="Belinda Newman"
$upn=(Get-MgUser | where {$_.DisplayName -eq $userName}).UserPrincipalName
Update-MgUser -UserId $upn -UsageLocation "FR"

Change properties for all user accounts

To change properties for all users, you can use a combination of the Get-MgUser and Update-MgUser cmdlets. The following example changes the usage location for all users to France:

Get-MgUser | ForEach-Object { Update-MgUser -UserId $_.Id -UsageLocation "FR" }

This command instructs PowerShell to:

  1. Get all of the information on the user accounts (Get-MgUser) and send it to the next command (|).

  2. Set the user location to France (Update-MgUser -UsageLocation FR).

Change properties for a specific set of user accounts

To change properties for a specific set of user accounts, you can use a combination of the Get-MgUser, Where, and Update-MgUser cmdlets. The following example changes the usage location for all the users in the Accounting department to France:

Get-MgUser -All | Where-Object {$_.Department -eq "Accounting"} | ForEach-Object {Update-MgUser -UserId $_.Id -UsageLocation "FR"}

This command instructs PowerShell to:

  1. Get all the information on the user accounts (Get-MgUser), and send it to the next command (|).

  2. Find all the user accounts that have their Department property set to "Accounting" (Where {$_.Department -eq "Accounting"}), and send the resulting information to the next command (|).

  3. Set the user location to France (Update-MgUser -UsageLocation FR).

See also

Manage Microsoft 365 user accounts, licenses, and groups with PowerShell

Manage Microsoft 365 with PowerShell

Get started with PowerShell for Microsoft 365