Export (0) Print
Expand All

Use Windows PowerShell to manage users and groups

 

Topic Last Modified: 2014-06-18

Summary: Use Windows PowerShell to Manage Office 365 using Windows PowerShell cmdlets, scripts, and batch processes.

If you are a SharePoint Online administrator who works with large lists of user accounts or groups and wants an easier way to manage them, you have come to the right place. Welcome!

Typically, graphical user interfaces are at their best when you have a one-off action to perform. But if you have to change thousands of user accounts, or if you have to perform some other action in bulk, you'll want to use Windows PowerShell! For example, suppose that your boss comes up to you and says, "Hey, we have a spreadsheet with 500 new user accounts, and we have to add them to some SharePoint sites and give them permissions. How quickly can you do that?" This would be a great place to use Windows PowerShell.

If you're brand new to Windows PowerShell, take a look at these introductory articles.

If you want more information on the SharePoint Online Management Shell, the following article is a great place to start: Introduction to the SharePoint Online management shell

You will learn how to perform common administrative tasks for users and groups in SharePoint Online by using the SharePoint Online Management Shell. After completing this article, you'll be better able to:

  • Get a list of sites, groups, and users.

  • Assign the users to groups.

  • Manage permissions for groups.

  • Add the groups to SharePoint Online sites.

  • Create a simple report of users

That might sound like lots of work, but don’t worry, with the SharePoint Online Management Shell, it’s fairly easy after you set it up.

We'll start by working with a single user account so that you can see how it works and how the syntax looks. Then, we'll crank it up and create several accounts using a comma separated-values (CSV) file. This means that you can export this file from an Excel 2013 spreadsheet and use it to create SharePoint Online user accounts. It’s almost magical.

NoteNote:
Because the URLs, user names, and group names that you'll use are specific to your environment, we'll use example URLs, user names, and group names in this article. We'll mark these with angle brackets, for example <tenant>. The scripts will work if you replace the example URLs, user names, and group names with data from your environment.

Before we get started on how to use Windows PowerShell to manage users and groups, let’s make sure we are properly prepared. Before starting, you should:

With all that ready, let’s connect to your Office 365 tenant. You use the Connect-SPOService command to connect. Here is what the syntax looks like:

Connect-SPOService -Url https://<tenant>-admin.sharepoint.com -credential admin@<tenant>.onmicrosoft.com

After you enter your tenant-specific information and press Enter, a dialog box will open asking for your administrator password. After you type the password, you are connected. Ready? Well, let’s go.

Before we start to manage users and groups, let’s get lists of your sites, groups, and users. You can then use this information to work through the example in this article.

The best place to start is to get a list of the site in your tenant. The syntax for this looks like this:

Get-SPOSite

Cut and paste this into your console, and it will display all the sites in your tenant.

And now you can get a list of the groups in your tenant. The syntax looks like this:

Get-SPOSite | ForEach-Object {Get-SPOSiteGroup -Site $_.Url} |Format-Table

Cut and paste this into your console.

Next, you can get a list of the users in your tenant. The syntax looks like this:

Get-SPOSite | ForEach-Object {Get-SPOUser -Site $_.Url}

Cut and paste this into your console.

You can use the Set-SPOUser command to add a user to the list of Site Collection Administrators on a site collection. This is how the syntax looks:

$tenant = "<tenant>"
# This is the Tenant Name. Value must be enclosed in double quotation marks, Example: "Contoso01"

$site = "<site>"
# This is the Site name. Value must be enclosed in double quotation marks, Example: "contosotest"

$user = "<loginname>"
# This is the users login name. Value must be enclosed in double quotation marks, Example "opalc"

Set-SPOUser -Site https://$tenant.sharepoint.com/sites/$site -LoginName $user@$tenant.onmicrosoft.com -IsSiteCollectionAdmin $true

There are a couple things to notice here. First, there are several ways that you can construct your commands. Here we have chosen to use variables to store the values for the action. This makes your scripts easier to use and understand. We have also included notes in the script (for example "# This is the Tenant Name…") to help you understand what the values should be.

So let’s try this command to add Opal Castillo the list of Site Collection Administrators on the ContosoTest site collection. This is how the actual command might look:

$tenant = "contoso1"
$site = "contosotest"
$user = "opalc"
Set-SPOUser -Site https://$tenant.sharepoint.com/sites/$site -LoginName $user@$tenant.onmicrosoft.com -IsSiteCollectionAdmin $true

You can actually cut and paste this above code into Notepad, change the variable values CONTOSO1, CONTOSOTEST, and OPALC to actual values from your environment and then paste this into your admin Windows PowerShell window, and it will work! Cool, right?

In this task, we'll use the Add-SPOUser command to add a user to a SharePoint group on a site collection. This is how the syntax looks:

$tenant = "<tenant>"
# This is the Tenant Name. Value must be enclosed in double quotation marks, Example: "Contoso01"

$site = "<site>"
# This is the Site name. Value must be enclosed in double quotation marks, Example: "contosotest"

$user = "<loginname>"
# This is the users login name. Value must be enclosed in double quotation marks, Example: "opalc"

$group = "<group>"
# This is the SharePoint security Group name. Value must be enclosed in double quotation marks, Example: "Auditors"

Add-SPOUser -Group $group -LoginName $user@$tenant.onmicrosoft.com -Site https://$tenant.sharepoint.com/sites/$site

Let’s add Glen Rife to the Auditors group on the ContosoTest site collection. This is how the actual script would look:

$tenant = "contoso1"
$site = "contosotest"
$user = "glenr"
$group = "Auditors"
Add-SPOUser -Group $group -LoginName $user@$tenant.onmicrosoft.com -Site https://$tenant.sharepoint.com/sites/$site

Again, you can just paste this into Notepad, replace the variable values with your values, and run it in the SharePoint Online Management console.

In this task, we will use the Set-SPOSiteGroup command to create a new SharePoint group and add it to the ContosoTest site collection. This is how the syntax looks:

$tenant = "<tenant>"
# This is the Tenant Name. Value must be enclosed in double quotation marks, Example: "Contoso01"

$site = "<site>"
# This is the Site name. Value must be enclosed in double quotation marks, Example: "contosotest"

$group = "<group>"
# This is the SharePoint security Group name. Value must be enclosed in double quotation marks, Example: "Auditors"

$level = "<permission level>"
# This is the level of permissions to assign to the group. Value must be enclosed in double quotation marks, Example: "View Only"

New-SPOSiteGroup -Group $group -PermissionLevels $level -Site https://$tenant.sharepoint.com/sites/$site
NoteNote:
You have to enclose any string with spaces in quotation marks. Group properties, such as permission levels, can be updated later by using the Set-SPOSiteGroup cmdlet.

Now, let’s add the Auditors group with View Only permissions to the Contoso Test site collection. This is how the actual script would look:

$tenant = "contoso1"
$site = "testsite"
$level = "View Only"
$group = "Auditors"
New-SPOSiteGroup -Group $group -PermissionLevels $level -Site https://$tenant.sharepoint.com/sites/$site

Again, you can just paste this into Notepad, replace the variable values with your values, and run it in the SharePoint Online Management console.

Sometimes, you have to remove a user from a site or even all sites. Perhaps the employee moves from one division to another or leaves the company. You can do this for one employee easily in the UI. But what if you move a complete division from one site to another? Again, estimated time to complete: approximately forever.

However by using the SharePoint Online Management Shell and CSV files, this is fast and easy. In this task, you'll use Windows PowerShell to remove a user from a site collection security group. Then you'll use a CSV file and remove lots of users from different sites.

We'll be using the Remove-SPOUser command to remove a single Office 365 user from a site collection group just so we can see the command syntax. Here is how the syntax looks:

$tenant = "<tenant>"
# This is the Tenant Name. Value must be enclosed in double quotation marks, Example: "Contoso01"

$site = "<site>"
# This is the Site name. Value must be enclosed in double quotation marks, Example: "contosotest"

$group = "<group>"
# This is the SharePoint security Group name. Value must be enclosed in double quotation marks, Example: "Auditors"

$user = "<loginname>"
# This is the user's login name. Value must be enclosed in double quotation marks, Example: "opalc"

Remove-SPOUser -LoginName $user@$tenant.onmicrosoft.com -Site https://$tenant.sharepoint.com/sites/$site

Let’s remove Bobby Overby from the site collection Auditors group. Sorry, Bobby. This is what the script looks like:

$tenant = "contoso1"
$site = "contosotest"
$user = "bobbyo"
$group = "Auditors"
Remove-SPOUser -LoginName $user@$tenant.onmicrosoft.com -Site https://$tenant.sharepoint.com/sites/$site -Group $group

Again, you can just paste this into Notepad, replace the variable values with your values, and run it in the console.

Suppose we wanted to remove Bobby from all the groups he is currently in. Here is how we would do that:

CautionCaution:
This is just to show how to do this. You should not run this command unless you really have to remove a user from every group, for example if the user leaves the company.
$tenant = "contoso1"
$user = "bobbyo"
Get-SPOSite | ForEach-Object {Get-SPOSiteGroup -Site $_.Url} | ForEach-Object {Remove-SPOUser -LoginName $user@$tenant.onmicrosoft.com -Site &_.Url}

In our scenario above, your boss came to you and said "Hey, we have a spreadsheet with 500 new user accounts, and we have to add them to some SharePoint sites and give them permissions. How quickly can you do that?" And we estimated that using the UI this would take forever. And if you used individual manually-coded scripts in the SharePoint Online Management Shell, it might take only half that long. However, you can combine scripts with information in a CSV file to create a simple, fast, and error-free way to add those users. Now, we’re talking!

The basic process is to create a CSV file that has headers (columns) that correspond to the parameters that the Windows PowerShell script needs. You can easily create such a list in Microsoft Excel 2013 and then export it as a CSV file. Then, you use a Windows PowerShell script to iterate through records (rows) in the CSV file, adding the users to groups and the groups to sites.

For example, let’s create a CSV file to define a group of site collections, groups, and permissions. Next, we will create a CSV file to populate the groups with users. Finally, we will create and run a simple Windows PowerShell script that creates and populates the groups.

The first CSV file will add one or more groups to one or more site collections and will have this structure:

Header:

Site,Group,PermissionLevels

Item:

https://<tenant>.sharepoint.com/sites/<site>,<site collection>,<group>,<level>

Here is an example file:

Site,Group,PermissionLevels
https://contoso1.sharepoint.com/sites/contosotest,Contoso Project Leads,Full Control
https://contoso1.sharepoint.com/sites/contosotest,Contoso Auditors,View Only
https://contoso1.sharepoint.com/sites/contosotest,Contoso Designers,Design
https://contoso1.sharepoint.com/sites/TeamSite01,XT1000 Team Leads,Full Control
https://contoso1.sharepoint.com/sites/TeamSite01,XT1000 Advisors,Edit
https://contoso1.sharepoint.com/sites/Blog01,Contoso Blog Designers,Design
https://contoso1.sharepoint.com/sites/Blog01,Contoso Blog Editors,Edit
https://contoso1.sharepoint.com/sites/Project01,Project Alpha Approvers,Full Control

The second CSV file will add one or more users to one or more groups and will have this structure:

Header:

Group,LoginName,Site

Item:

<group>,<login>,https://<tenant>.sharepoint.com/sites/<site>

Here is an example file:

Group,LoginName,Site
Contoso Project Leads,bobbyo@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/contosotest
Contoso Auditors,allieb@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/contosotest
Contoso Designers,bonniek@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/contosotest
XT1000 Team Leads,dorenap@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/TeamSite01
XT1000 Advisors,garthf@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/TeamSite01
Contoso Blog Designers,janets@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/Blog01
Contoso Blog Editors,opalc@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/Blog01
Project Alpha Approvers,robinc@contoso1.onmicrosoft.com,https://contoso1.sharepoint.com/sites/Project01

And now, the magical script that will take both files and do all the work while you are out getting coffee. All you have to do is to save this script to your local drive and add the .ps1 extension. Then, you must have the two CSV files saved to your drive. Here is the script:

Import-Csv C:\GroupsAndPermissions.csv | ForEach-Object {New-SPOSiteGroup -Group $_.Group -PermissionLevels $_.PermissionLevels -Site $_.Site}
Import-Csv C:\Users.csv | ForEach-Object {Add-SPOUser -Group $_.Group -LoginName $_.LoginName -Site $_.Site}

The script imports the CSV file contents and uses the values in the columns (in bold) to populate the parameters of the New-SPOSiteGroup and Add-SPOUser commands. In our example, we are saving this to the drive C, but you can save it wherever you want.

Suppose you save the script as: C:\UsersAndGroup.ps1. And the two CSV files as C:\GroupsAndPermissions.csv and C:\Users.csv. To run the script, all you have to do is this:

Cd c:\
.\UsersAndGroup.ps1

The first part is to navigate to the directory where you have the .ps1 file, and the second line runs the script. Now, you can go get coffee while Windows PowerShell does all the work.

Now, let’s remove a bunch of people for several groups in different sites. Let’s use the very same CSV file from earlier in this article. All you have to do is to save this script to your local drive, and add the .ps1 extension. Then, you must save the file to your drive. Here is the script:

Import-Csv C:\Users.csv | ForEach-Object {Remove-SPOUser -LoginName $_.LoginName -Site $_.Site -Group $_.Group}

Suppose you save the script as: C:\RemoveUsers.ps1. And the CSV file as C:\Users.csv. To run the script, all you have to do is this:

.\RemoveUsers.ps1

Then, you go get coffee, and perhaps a donut.

You might want to get a simple report for a few sites and display the users for those sites, their permission level, and other properties. This is how the syntax looks:

$tenant = "<tenant>"
# This is the Tenant Name. Value must be enclosed in double quotes, Example: "Contoso01"

$site = "<site>"
# This is the Site name. Value must be enclosed in double quotes, Example: "contosotest"

Get-SPOUser -Site https://$tenant.sharepoint.com/sites/$site | select * | Format-table -Wrap -AutoSize | Out-File c\UsersReport.txt -Force -Width 360 -Append

This will grab the data for these three sites and write them to a text file on your local drive. Note that the parameter –Append will add new content to an existing file.

If we ran the script for the ContosoTest, TeamSite01, and Project01 sites on the Contoso1 tenant, the script would look like this:

$tenant = "contoso1"
$site = "contosotest"

Get-SPOUser -Site https://$tenant.sharepoint.com/sites/$site | Format-Table -Wrap -AutoSize | Out-File c:\UsersReport.txt -Force -Width 360 -Append

$site = "TeamSite01"

Get-SPOUser -Site https://$tenant.sharepoint.com/sites/$site |Format-Table -Wrap -AutoSize | Out-File c:\UsersReport.txt -Force -Width 360 -Append

$site = "Project01"

Get-SPOUser -Site https://$tenant.sharepoint.com/sites/$site | Format-Table -Wrap -AutoSize | Out-File c:\UsersReport.txt -Force -Width 360 -Append

Note that we had to change only the $site variable. The $tenant variable keeps its value through all three runs of the command.

However, what if you wanted to do this for every site? You can do this without having to type all those websites by using this command:

Get-SPOSite | ForEach-Object {Get-SPOUser -Site $_.Url} | Format-Table -Wrap -AutoSize | Out-File c:\UsersReport.txt -Force -Width 360 -Append

This report is fairly simple, and you can definitely add more code to create more specific reports or reports that include more detailed information. But this is good enough to give us an idea of how to use the SharePoint Online Management Shell to manage users in the SharePoint Online environment.

For more about Windows PowerShell, take a look at the Introducing Windows PowerShell content.

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft