User management scenarios for Office 365 PowerShell

Use these PowerShell scenarios to quickly add user accounts from a file, assign licenses, manage distribution group membership, and set passwords.

Automate the importing of multiple users

You can automate importing multiple users into Office 365 and save a lot of time. To import a large number of users, you need to first prepare a comma-separated value (CSV) file with the relevant user information. The minimum information required to create a user account is a Display Name, and a User Principal Name (UPN).

A UPN is the name of a user in an e-mail address format. The user name (or "username") is followed by the "at sign" followed by the name of the Internet domain of your Office 365 subscription. An example UPN is belindan@contoso.com. You can also provide data for any writable user account property, such as location, contact numbers, and addresses.

For basic user account properties, such as the UPN and a display name, prepare a CSV file with the following two column headers:

  • UserPrincipalName,DisplayName

Next, add a new user account on each row of the CSV by typing the UPN and display name, separated by a comma.

Note: Because you are not specifying a password for each new account, Office 365 will generate them.

Store the CSV file in a location that you can access, such as C:\O365Admin\NewUsers.CSV. Now you are ready to create user accounts.

To begin, you will need to connect to Office 365 with the Windows Azure Active Directory Module for Windows PowerShell. See Connect to Office 365 PowerShell for the instructions.

Next, fill in the path and file name between the double-quotes, removing the instruction text and the < and > characters.

$fileName="<path and file name of the CSV file, example C:\O365Admin\NewUsers.CSV>"
Import-Csv $fileName | ForEach { New-MsolUser -UserPrincipalName  $_.UserPrincipalName -DisplayName $_.DisplayName }

Run the resulting commands from the Windows Azure Active Directory Module for Windows PowerShell window.

For more detailed user account information, prepare a CSV file with the following column headers, and populate as many user rows as needed:

  • UserPrincipalName,DisplayName,FirstName,LastName,Title,Password,UsageLocation,Office,Department,MobilePhone,StreetAddress,City,State,PostalCode,Country

Note: The column headers should have no spaces, as each needs to be referenced by the $_. element of the Import-Csv command. Only the UserPrincipalName and DisplayName fields are required and blank values will be skipped. The UsageLocation code is the two-character ISO code for the user's region.

Store the CSV file in a location that you can access, such as C:\O365Admin\NewUsers.CSV. Now you are ready to import them as user accounts.

Fill in the file name for your CSV file, and then run the resulting commands.

$fileName="<path and file name of the CSV file, example C:\O365Admin\NewUsers.CSV>"
Import-Csv $fileName | ForEach { New-MsolUser -UserPrincipalName   $_.UserPrincipalName -FirstName $_.FirstName -LastName $_.LastName -DisplayName $_.DisplayName -Title $_.Title -Department $_.Department -Office $_.Office -MobilePhone $_.MobilePhone -StreetAddress $_.StreetAddress -City $_.City -State $_.State -PostalCode $_.PostalCode -Country $_.Country -Password $_.Password }

Assign licenses in Office 365

For users to have full access to Office 365, they need to be assigned an Office 365 license. In this scenario, you assign licenses to user accounts.

To begin, you will need to connect to Office 365 with the Windows Azure Active Directory Module for Windows PowerShell. See Connect to Office 365 PowerShell for the instructions.

Before you can assign a license to a user, you must set the Usage Location for that user account based on the two-character ISO code for their region. The Usage Location specifies the country in which the service is to be used and determines which licensed features are available for that region. For example, US is for the United States of America. Here is an example of setting the Usage Location based on a user account's UPN:

Set-MsolUser -UserPrincipalName user@contoso.com -UsageLocation US

To view the list of available licenses, their account SKUs, and the quantity remaining for assignment, run the following command:

Get-MsolAccountSku

Next, fill in the license and UPN of the user account, and then run the resulting commands from the Windows Azure Active Directory Module for Windows PowerShell window.

$license="<the appropriate value of AccountSkuId from the Get-MsolAccountSku command>"
$userUPN="<the UPN of the user account>"
UserLicense -UserPrincipalName $userUPN -AddLicenses $license

Assign licenses to multiple users

In the previous scenario, you assigned a license to a single user account. Assigning licenses to multiple users requires a few more steps but the time spent will be worth it for a large number of user accounts.

To begin, you will need to connect to Office 365 with the Windows Azure Active Directory Module for Windows PowerShell. See Connect to Office 365 PowerShell for the instructions.

First, display the list of available licenses, their account SKUs, and the quantity remaining for assignment with this command:

Get-MsolAccountSku

To display a list of unlicensed users, use this command:

Get-MsolUser -UnlicensedUsersOnly

To save the list of unlicensed users to a CSV file from which you can use to pick and choose user accounts to assign licenses, fill in the path and file name, and then run the resulting commands.

$fileName="<path and file name of the CSV file, example: c:\reports\Unlicensed_Users.CSV>"
Get-MsolUser -UnlicensedUsersOnly | Export-Csv $fileName

You can also use the Where command to display a list of unlicensed user accounts based on a more specific criteria, such as those in the United States. Here is an example:

Get-MsolUser -All -UnlicensedUsersOnly | Where {$_.Country -eq "United States"}

Use these commands to specify a user account property and its required value and display a specific set of unlicensed users, and then run the resulting commands.:

$userPropertyName="<name of the user property>"
$userPropertyValue="<value of the user property>"
Get-MsolUser -All -UnlicensedUsersOnly | Where {$_.$userPropertyName -eq $userPropertyValue}

To get the list of user account properties, fill in any user account UPN, and then run the resulting commands.

$userUPN="<the UPN of any user account>"
Get-MsolUser -UserPrincipalName $userUPN | Select * | More

The following example displays all unlicensed users in the city of London:

$userPropertyName="City"
$userPropertyValue="London"
Get-MsolUser -All -UnlicensedUsersOnly | Where {$_.$userPropertyName -eq $userPropertyValue}

Once you have identified the set of user accounts, you combine it with the Set-MsolUserLicense cmdlet to assign licenses to each of them. Fill in the license, the property name and its vale, and then run the resulting commands.

$license="<the appropriate value of AccountSkuId from the Get-MsolAccountSku command>"
$userPropertyName="<name of the user property>"
$userPropertyValue="<value of the user property>"
Get-MsolUser -All -UnlicensedUsersOnly | Where {$_.$userPropertyName -eq $userPropertyValue}  | Set-MsolUserLicense -AddLicenses $license

Here is an example that assigns Contoso's Office 365 E5 license to all unlicensed user accounts in the city of London:

$license="contoso:ENTERPRISEPACK"
$userPropertyName="City"
$userPropertyValue="London"
Get-MsolUser -All -UnlicensedUsersOnly | Where {$_.$userPropertyName -eq $userPropertyValue}  | Set-MsolUserLicense -AddLicenses $license

Manage distribution group recipients

You can use distribution groups to create e-mail distribution lists. Distribution groups can be used only with e-mail applications such as Microsoft Outlook to send e-mail messages to collections of users. In this scenario, you use PowerShell to manage the recipients of a distribution group.

To begin, you will need to connect to Exchange Online. To connect to Exchange Online with an account user name and password, see Connect to Exchange Online PowerShell. To install the Microsoft Exchange Online Remote PowerShell Module and connect with MFA, see Connect to Exchange Online PowerShell using multi-factor authentication.

To add a recipient to a distribution group, fill in the distribution group name and UPN of the user account, and then run the resulting commands.

$distName="<name of the distribution group>"
$userUPN="<the UPN of the user account>"
Add-DistributionGroupMember -Identity $distName -Member $userUPN

To remove a recipient of a distribution group, fill in the distribution group name and UPN of the user account, and then run the resulting commands.

$distName="<name of the distribution group>"
$userUPN="<the UPN of the user account>"
Remove-DistributionGroupMember -Identity $distName -Member $userUPN

Set the passwords for multiple user accounts

Use this scenario to set the password on a group of user accounts. For example, you have a new group of volunteers who come in once a week to help out or you provide demo workstations for use at a conference.

A bulk password change can be useful to reset the passwords on reusable accounts on a regular basis. By designating a group of users by a department or other criteria, you can bulk reset passwords based on that criteria. The first step is to export the Office 365 user account names to a CSV file.

To export a list based on a user account property and a specific value to a CSV file, fill in the property name, its value, and the file name of the CSV, and then run the resulting commands.

$userPropertyName="<name of the user property>"
$userPropertyValue="<value of the user property>"
$fileName="<path and file name of the CSV file, example c:\O365Admin\userlist.csv>"
Get-MsolUser | Where {$_.$userPropertyName -eq $userPropertyValue} | select UserPrincipalName | Export-Csv $fileName -NoTypeInformation

Here is an example that exports all the members of the Volunteers department to the file named c:\O365admin\volunteerslist.csv:

$userPropertyName="Department"
$userPropertyValue="Volunteers"
$fileName="c:\O365admin\volunteerslist.csv"
Get-MsolUser | Where {$_.$userPropertyName -eq $userPropertyValue} | Select UserPrincipalName | Export-Csv $fileName -NoTypeInformation

Review the names contained in the CSV file to ensure you have identified the correct users before resetting any passwords. Once we have a validated list of users in CSV format, there are three simple methods to create and assign a new password to each user.

  1. Specify a new password and assign the same password to all users in the CSV file.

    Fill in the new password and the file name of the CSV, and then run the resulting commands.

    $pass="<the new password>"
    $fileName="<path and file name of the CSV file, example c:\O365Admin\userlist.csv>"
    Import-Csv $fileName | ForEach {Set-MsolUserPassword -UserPrincipalName $_.UserPrincipalName -NewPassword $pass -ForceChangePassword $True}
  2. Manually define a new password for each user in the CSV file.

    For this option, you must modify the CSV file. Add a column next to the UserPrincipalName labeled Password and then assign a password to all the users in the list. Fill in the file name of the CSV, and then run the resulting commands.

    $fileName="<path and file name of the CSV file, example c:\O365Admin\userlist.csv>"
    Import-Csv $fileName | ForEach {Set-MsolUserPassword -UserPrincipalName $_.UserPrincipalName -NewPassword $_.Password -ForceChangePassword $True}
  3. Have Office 365 automatically generate a password for each user account in the CSV file.

    Fill in the file name of the CSV, and then run the resulting commands.

    $fileName="<path and file name of the CSV file, example c:\O365Admin\userlist.csv>"
    Import-Csv $fileName | ForEach {[string[]]$a+= $_.UserPrincipalName + "  " + (Set-MsolUserPassword -UserPrincipalName $_.UserPrincipalName -ForceChangePassword $True)} ;$a

Note: All three of these options enforce a password change the first time the user signs in with the user account. To prevent this, remove -ForceChangePassword $True from the Set-MSolUserPassword command.

See Also

PowerShell for Office 365 administrators

Office 365 PowerShell scenarios

Setup scenarios for Office 365 PowerShell

Reporting scenarios for Office 365 PowerShell

More functionality scenarios for Office 365 PowerShell

Office 365 PowerShell community resources

Expand your skills
Explore training
Get new features first
Join Office Insiders

Was this information helpful?

Thank you for your feedback!

Thank you for your feedback! It sounds like it might be helpful to connect you to one of our Office support agents.

×