Connect to all Office 365 services in a single Windows PowerShell window

 

Topic Last Modified: 2016-05-17

Summary: Connect Windows PowerShell to all Office 365 services in a single Windows PowerShell window.

When you use PowerShell to manage Office 365, it is possible to have up to five different Windows PowerShell sessions open at the same time corresponding to Office 365 admin center, SharePoint Online, Exchange Online, Skype for Business Online, and the Security & Compliance Center) . With five different connection methods in separate Windows PowerShell sessions, your desktop could look like this:

Five Windows PowerShell consoles running at once

This is not optimal for managing Office 365 because you can’t exchange data among those five windows for cross-service management. This topic describes how to use a single instance of Windows PowerShell from which you can manage Office 365, Skype for Business Online, Exchange Online, SharePoint Online, and the Security & Compliance Center.

See the following:

Before you begin

The short version (instructions without explanations)

The long version (instructions with detailed explanations)

Before you can manage all of Office 365 from a single instance of Windows PowerShell, consider the following prerequisites:

This section presents the connection steps without in-depth explanations. If you have questions or want more information, you can read rest of the topic. The step numbers here match the step-numbered sections in the rest of the topic:

  1. Open Windows PowerShell as an administrator (use Run as administrator).

  2. Run this command, and enter your Office 365 work or school account credentials.

    $credential = Get-Credential
    
  3. Run these commands to connect to Office 365.

    Import-Module MsOnline
    
    Connect-MsolService -Credential $credential
    
  4. Run these commands to connect to SharePoint Online. Replace domainhost with the actual value for your domain. For example, for litwareinc.onmicrosoft.com, the domainhost value is litwareinc.

    Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking
    
    Connect-SPOService -Url https://domainhost-admin.sharepoint.com -credential $credential
    
  5. Run these commands to connect to Skype for Business Online. A warning about increasing the WSMan NetworkDelayms value is expected the first time you connect and should be ignored.

    Import-Module SkypeOnlineConnector
    
    $sfboSession = New-CsOnlineSession -Credential $credential
    
    Import-PSSession $sfboSession
    
  6. Run these commands to connect to Exchange Online.

    $exchangeSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri "https://outlook.office365.com/powershell-liveid/" -Credential $credential -Authentication "Basic" -AllowRedirection
    
    Import-PSSession $exchangeSession -DisableNameChecking
    
  7. Run these commands to connect to the Security & Compliance Center.

    $ccSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid/ -Credential $credential -Authentication Basic -AllowRedirection
    
    Import-PSSession $ccSession -Prefix cc
    
    NoteNote:
    The text prefix "cc" is added to all Security & Compliance Center cmdlet names so you can run cmdlets that exist in both Exchange Online and the Security & Compliance Center in the same Windows PowerShell session. For example, Get-RoleGroup becomes Get-ccRoleGroup in the Security & Compliance Center.
  8. When you are ready to close down, run this compound command before you close the Windows PowerShell window.

    Remove-PSSession $sfboSession ; Remove-PSSession $exchangeSession ; Remove-PSSession $ccSession ; Disconnect-SPOService
    

If you're running Windows 8, Windows 8.1, Windows Server 2012 R2, or Windows Server 2012 R2, do this:

  1. Use any of these methods to find the shortcut for Windows PowerShell:

    • On the Start screen, click an empty area, and type Windows PowerShell.

    • On the desktop or the Start screen, press the Windows key+Q. In the Search charm, type Windows PowerShell.

    • On the desktop or the Start screen, move your cursor to the upper-right corner, or swipe left from the right edge of the screen to show the charms. Select the Search charm, and enter Windows PowerShell.

  2. In the results, right-click Windows PowerShell, and select Run as administrator.

  3. If the User Account Control dialog box appears, select Yes to verify that you want to run Windows PowerShell under administrator credentials.

If you’re running Windows 7 SP1 (or Windows Server 2008 R2 SP1), do this:

  1. On the Start menu, select All Programs > Accessories > Windows PowerShell. Right-click Windows PowerShell, and then select Run as administrator.

  2. If the User Account Control dialog box appears, select Yes to verify that you want to run Windows PowerShell under administrator credentials.

You must run Windows PowerShell as an administrator. If you don’t, you’re going to get an error message similar to this when you try to import one of the required modules.

The specified module 'Microsoft.Online.SharePoint.Online.PowerShell' was not loaded because no valid module file was found in any directory.

The only way to remedy the situation is to close Windows PowerShell and restart it as an administrator. Here's a quick and easy way to tell if you're running Windows PowerShell as an administrator: the prompt is PS C:\Windows\System32>, not PS C:\Users\UserName>.

Return to top

The credentials object provides an encrypted way to pass your user name and password to Windows PowerShell. To create a credentials object, run the following command in Windows PowerShell.

$credential = Get-Credential
NoteNote:
$credential is a variable that will store the credentials object. You don’t have to name the variable $credential, but doing so makes it easier to remember which variable contains the credentials object. (And that’s important, because we’ll reuse this variable several times.) That will also make it easier for you to follow our examples, because this article will always use $credential to represent the credentials object.

Windows PowerShell will then display a dialog box that looks like this.

Blank Credentials request dialog box.

Type your work or school account user name in the User name box, using the format username@domainname (for example, kenmyer@litwareinc.onmicrosoft.com); type your password in the Password box; and then click OK:

Completed Credentials request dialog box.

Note that, as is often the case, you won’t see any sort of confirmation that the credentials object was created. (Windows PowerShell typically tells you when things go wrong but doesn’t always tell you when things go right.) If you want to verify that the credentials object was created, type the following in Windows PowerShell and then press Enter.

$credential

You should then see something similar to this on the screen.

UserName                               Password
--------                               --------
kenmyer@litwareinc.onmicrosoft.com     System.Security.SecureString

One thing to keep in mind here is that the Get-Credential cmdlet only creates the credentials object; it does not authenticate you or otherwise verify that the user name and password you supplied are correct. For example, suppose you mistyped the user name as eknmyer@litwareinc.onmicrosoft.com. If you do that, Get-Credential will create a credentials object using that user name, and without checking to see if that is actually a valid user name. You won't know whether you have created a truly valid credentials object until you actually use that object to try to connect to the Office 365 services.

We’ll start by connecting to Office 365 itself.

The first thing we need to do here is import the Office 365 module (the Windows Azure Active Directory Module for Windows PowerShell). To do that, run this command in Windows PowerShell.

Import-Module MsOnline

If you want to verify that the module was imported, run this command.

Get-Module

Somewhere in the list of modules that are returned by this command you should see something that looks like this: Manifest 1.0 MSOnline {Add-MsolForeignGroupToRole, Add-MsolG...}.

If you see MSOnline listed, that means that everything went according to plan.

With the credentials object created (see Step 2: Create a Windows PowerShell credentials object) and with the MsOnline module loaded, we can now connect to Office 365 by using the Connect-MsolService cmdlet and the following command.

Connect-MsolService -Credential $credential

Notice that all you have to provide is the credentials object ($credential). Based on those credentials, Office 365 will automatically connect you to the correct domain. You do not have to specify your domain name when running Connect-MsolService.

To verify that you really are connected to Office 365, run this command.

Get-MsolDomain

In return, you should get back something similar to this.

Name                         Status          Authentication
----                         ------          --------------
litwareinc.onmicrosoft.com   Verified        Managed

Import the SharePoint Online module with the following command:

Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking

The DisableNameChecking switch suppresses this warning.

WARNING: The names of some imported commands from the module 'Microsoft.Online.SharePoint.PowerShell' include unapproved verbs that might make them less discoverable. To find the commands with unapproved verbs, run the Import-Module command again with the Verbose parameter. For a list of approved verbs, type Get-Verb.

In order to connect to SharePoint Online, you need to supply two pieces of information: your credentials and the URL of your SharePoint Online admin site. The credentials part is easy: we’ve already stored that in the variable $credential (see Step 2: Create a Windows PowerShell credentials object). As for the URL of your admin site, that’s easy enough to determine, as well. Suppose your Office 365 domain name is litwareinc.onmicrosoft.com.

To determine the admin site URL, do this:

  1. Start by using the prefix https://.

  2. Add the domain host portion of your domain name. For example, for litwareinc.onmicrosoft.com, the domain host name is litwareinc. For contoso.onmicrosoft.com, the domain host name is contoso.

  3. Add a hyphen (-) followed by admin.sharepoint.com.

In other words:

https:// + litwareinc + -admin.sharepoint.com = https://litwareinc-admin.sharepoint.com

After you’ve constructed the URL, you can then use that URL and your credentials object to connect to SharePoint Online. Just call the Connect-SPOService cmdlet, using a command similar to this one.

Connect-SPOService -Url https://litwareinc-admin.sharepoint.com -credential $credential

To verify that the connection has been made, run the following command in Windows PowerShell.

Get-SPOSite

You should get a list of all your SharePoint Online sites.

Url                                       Owner          Storage Quota
---                                       -----          -------------
http://litwareinc-public.sharepoint.com/                 1000
https://litwareinc.sharepoint.com/                       1000
https://litwareinc.sharepoint.com/search                 1000

Your Office 365 commands (the ones described in Step 3: Connect to Office 365) will still work. (Try running Get-MsolUser, and see for yourself.) That means that you can now manage both Office 365 and SharePoint Online from the same instance of Windows PowerShell.

Connecting to Skype for Business Online (and to Exchange Online or the Security & Compliance Center) is different than connecting to Office 365 or to SharePoint Online. That’s because the Skype for Business Online and Exchange Online cmdlets don’t get installed on your computer like the Office 365 and the SharePoint Online cmdlets do. Instead, each time you sign in, the appropriate cmdlets are temporarily copied to your computer. When you sign off, those cmdlets are then removed from your computer.

In order to connect to Skype for Business Online, you need to import the Skype for Business Online module. To do that, run this command.

Import-Module SkypeOnlineConnector

The first time you do this, you might see the following warning message, which you can safely ignore.

WARNING: WSMan NetworkDelayms has been set to 30000 milliseconds. The previous value was 5000 milliseconds.
WARNING: To improve the performance of the Lync Online Connector, it is recommended that the network delay be set to
30000 milliseconds (30 seconds). However, you can use Set-WinRMNetworkDelayMS to change the network delay to any
integer value.

After the module has been imported, run this command.

$sfboSession = New-CsOnlineSession -Credential $credential

We have created a remote PowerShell session. In this case, that means that we’ve connected to an instance of Windows PowerShell running on one of the Office 365 servers.

Although we’ve made a connection to Office 365, we haven’t downloaded the scripts, cmdlets, and other items needed to manage Skype for Business Online. To do that, we have to run this command.

Import-PSSession $sfboSession

When you import the Windows PowerShell session, you should see a progress bar similar to the following, a progress bar that reports on all the Skype for Business Online cmdlets being imported to your computer.

Lync Online progress bar.

When the progress bar disappears, you should then see output similar to the following.

ModuleType Version    Name               ExportedCommands
---------- -------    ----               ----------------
Script     1.0        tmp_swc5mp4v.1ck  {Copy-CsVoicePolicy, Disabl...

Run this command, which creates a remote Windows PowerShell session with Exchange Online.

$exchangeSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri "https://outlook.office365.com/powershell-liveid/" -Credential $credential -Authentication "Basic" -AllowRedirection
NoteNote:
Why is the command for connecting to Exchange Online more complicated than the command to connect to Skype for Business Online? Technically, it’s not: both commands do the exact same thing. However, the Skype for Business Online team created its own cmdlet—New-CsOnlineSession—that hides some of the parameters (like Authentication and AllowRedirection) that are used when connecting to Exchange Online. Instead of requiring you to type that information yourself, the Authentication and AllowRedirection parameters are effectively built in to the New-CsOnlineSession cmdlet. You have to type those parameters when connecting to Exchange Online because Exchange Online uses the standard New-PSSession cmdlet to connect to Office 365. The disadvantage is that you have a little more typing to do. The advantage is that you don’t have to download and install an Exchange Online module.

All you have to do now is import this remote session, just like we did with Skype for Business Online.

Import-PSSession $exchangeSession -DisableNameChecking

You should see something similar to this on the screen.

ModuleType Version  Name             ExportedCommands
---------- -------  ----             ----------------
Script     1.0      tmp_nweiqjvl.geu {Add-AvailabilityAddressSpace...

Now try running this command.

Get-AcceptedDomain

In return, you should see information about your Office 365 domains that are configured for email addresses in Exchange Online.

Name            DomainName          DomainType      Default
----            ----------          ----------      -------
litwareinc.com  litwareinc.com      Authoritative   True

The Security & Compliance Center is a service in Office 365 that lets you to manage compliance features from one location. For more information, see Office 365 Security & Compliance Center.

The connection instructions for the Security & Compliance Center are very similar to those for Exchange Online, but with an added twist, which you'll see in a moment.

Run this command, which creates a remote PowerShell session with the Security & Compliance Center.

$ccSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid/ -Credential $credential -Authentication Basic -AllowRedirection

Now run this command:

Import-PSSession $ccSession -Prefix cc

Again, this command is very similar to the command for Exchange Online. The DisableNameChecking switch isn't required because there are no unapproved verbs in the Security & Compliance Center. But what about that additional -Prefix cc parameter and value? That's the added twist we told you about.

Exchange Online and the Security & Compliance Center share some cmdlets that have exactly the same names and provide the same functionality. Get-RoleGroup is an example.

So what happens if you try to import two sessions that contain cmdlets with the same name? They collide. You'll get a big yellow warning message that says, WARNING: Proxy creation has been skipped for the following command: followed by the list of conflicting cmdlets that couldn't be imported. The end result? You can run Get-RoleGroup in Exchange Online because you connected there first, but you can't run Get-RoleGroup in the Security & Compliance Center because you connected there last and the conflicting cmdlets refused to import.

The easiest way to deal with this problem is to add an arbitrary text prefix to the imported Security & Compliance Center cmdlets. We did that using the Prefix parameter with the value "cc" on the Import-PSSession cmdlet. What did that do for us? It eliminated the conflicts by (slightly) changing the Security & Compliance Center cmdlet names for this session. All of the imported Security & Compliance Center cmdlets now start with "cc" in the noun part of the cmdlet name (to the right of the "-"). For example, the contentious Get-RoleGroup cmdlet becomes Get-ccRoleGroup for the Security & Compliance Center so it doesn't conflict with Get-RoleGroup for Exchange Online.

The downside? All Security & Compliance Center cmdlet names receive the "cc" prefix—even unique cmdlets that don't need it. For example, Get-ComplianceSearch becomes Get-ccComplianceSearch even though there is no such cmdlet in Exchange Online. It's a bit of a pain, but not too bad when you consider the benefits of managing all Office 365 services in a single Windows PowerShell session. Just remember to add "cc" to the cmdlet names for all procedures in the Security & Compliance Center.

If all goes well, you'll see something similar to this:

ModuleType Version  Name             ExportedCommands
---------- -------  ----             ----------------
Script     1.0      tmp_xbbx5exr.ehm {Add-ccRoleGroupMember, Get-ccAdminAuditLogConfig, Get-ccA...

Now you are free to manage all Office 365 services in a single Windows PowerShell session.

If you just close the Windows PowerShell window, your Skype for Business Online remote connection will remain active for the next 15 minutes or so. Because Skype for Business Online limits the number of simultaneous connections that any one person or any one domain can have open, that could be a problem. With Skype for Business Online, an individual administrator can have, at most, three open connections at one time, and a domain can have a maximum of nine open connections. If you sign in to Skype for Business Online and then exit without properly closing the session, that session remains open for the next 15 minutes or so. As a result, that’s one fewer connection available to you or to other administrators in your domain.

Instead, let’s close the remote sessions for Skype for Business Online, Exchange Online, and the Security & Compliance Center gracefully. Before we do that, run this command.

Get-PSSession

The Get-PSSession cmdlet should show you that you have at least three remote sessions open, one for Skype for Business Online, one for Exchange Online and one for the Security & Compliance Center (it’s possible you could have more than three remote sessions running, depending on whether you’ve used this instance of Windows PowerShell to connect to something else besides the Office 365 services). You should see something similar to the following.

Id Name     ComputerName     State   ConfigurationName    Availability
-- ----     ------------     -----   -----------------    ------------
 1 Session1 webdir0a.onl...  Opened  Microsoft.PowerShell    Available
 2 Session2 outlook.offi...  Opened  Microsoft.Exchange      Available
 3 Session3 ps.complianc...  Opened  Microsoft.Exchange      Available

To close these three sessions, run these commands one at a time. The first command closes the Skype for Business Online session, the second closes the Exchange Online session, and the third closes the Security & Compliance Center session.

Remove-PSSession $sfboSession
Remove-PSSession $exchangeSession
Remove-PSSession $ccSession

If you now run the Get-PSSession cmdlet, you should see nothing at all (unless you have other remote sessions up and running).

Windows PowerShell console with no remote sessions
NoteNote:
If you’d prefer to close all your remote sessions at the same time, you can use this command:
Get-PSSession | Remove-PSSession

If you now try running a cmdlet from any of these closed sessions (for example, Get-CsMeetingConfiguration in Skype for Business Online) you'll get an error message that's similar to this one.

Get-CsMeetingConfiguration : The term 'Get-CsMeetingConfiguration' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

We get that error message because the cmdlets for Skype for Business Online, Exchange Online, and the Security & Compliance Center were deleted when we closed the remote sessions.

To close the SharePoint Online session, type this command.

Disconnect-SPOService

If you now try to run the Get-SPOSite cmdlet, you’ll get an error message like this.

get-sposite : No connection available. Use Connect-SPOService before running this CmdLet.

You can’t retrieve site information because you’re no longer connected to SharePoint Online.

As for your connection to Office 365, although there’s a Connect-MsolService cmdlet, there’s no corresponding Disconnect-MsolService cmdlet. So for Office 365, just close the Windows PowerShell window. Nevertheless, it’s still a good idea to do this last so you can properly disconnect from SharePoint Online, Skype for Business Online, Exchange Online, and the Security & Compliance Center.

 
Show: