Manage SharePoint Online users and groups with Office 365 PowerShell

 

Applies to: SharePoint Online, SharePoint Online Enterprise (E3 and E4)

Topic Last Modified: 2016-08-16

Use Office 365 PowerShell to manage SharePoint Online users, groups, and sites.

If you are a SharePoint Online who works with large lists of user accounts or groups and wants an easier way to manage them, you can use Office 365 PowerShell.

The procedures in this topic require you to connect to SharePoint Online. For instructions, see Connect to SharePoint Online PowerShell.

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

Get a list of the sites in your tenant with this command:

Get-SPOSite

Get a list of the groups in your tenant with this command:

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

Get a list of the users in your tenant with this command:

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

You 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

This example uses variables to store values and has notes in the script (for example "# This is the Tenant Name…") to help you understand what those values should be.

For example, this set of commands adds Opal Castillo (user name opalc) the list of Site Collection Administrators on the ContosoTest site collection in the contoso1 tenancy:

$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 these commands into Notepad, change the variable values for $tenant, $site, and $user to actual values from your environment, and then paste this into your SharePoint Online Management Shell window.

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

For example, let’s add Glen Rife (user name glenr) to the Auditors group on the ContosoTest site collection in the contoso1 tenancy:

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

You 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.

For example, let’s add the Auditors group with View Only permissions to the Contoso Test site collection in the contoso1 tenancy:

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

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 this is not easily done when you have to move a complete division from one site to another.

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

For example, let’s remove Bobby Overby from the site collection Auditors group in the Contoso Test site collection in the contoso1 tenancy:

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

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

$tenant = "contoso1"
$user = "bobbyo"
Get-SPOSite | ForEach-Object {Get-SPOSiteGroup -Site $_.Url} | ForEach-Object {Remove-SPOUser -LoginName $user@$tenant.onmicrosoft.com -Site &_.Url}
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.

To add a large number of accounts to SharePoint sites and give them permissions, you can use the Office 365 admin center, individual PowerShell commands, or PowerShell an a CSV file. Of these choices, the CSV file is the fastest way to automate this task.

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 Excel 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

For the next step, you must have the two CSV files saved to your drive. Here are the commands that use both CSV files and to add permissions and group membership:

Import-Csv C:\O365Admin\GroupsAndPermissions.csv | ForEach-Object {New-SPOSiteGroup -Group $_.Group -PermissionLevels $_.PermissionLevels -Site $_.Site}
Import-Csv C:\O365Admin\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.

Now, let’s remove a bunch of people for several groups in different sites using the same CSV file. Here is the command:

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

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.

For example, let's run a report on the ContosoTest, TeamSite01, and Project01 sites for the Contoso1 tenant:

$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 add more code to create more specific reports or reports that include more detailed information. But this should give you an idea of how to use the SharePoint Online Management Shell to manage users in the SharePoint Online environment.

Show: