Connecting to Office 365/Exchange

powershell

Last update: Version 1.81, November 16th, 2017

Almost 3 years ago, I wrote an article on how to enhance the PowerShell Integrated Scripting Environment, or ISE. That seemed adequate for the Exchange admin back then, who mostly connected their PowerShell session to their his on-premises environment, and perhaps occasionally a bit of Exchange Online.

Fast forward to 2015, most modern Exchange administrators not only require a connection – if any – to their Exchange on-premises environment, but likely to one or more of the Office 365 services as well, including Exchange On-Premises, Azure Active Directory, Exchange Online Protection, Microsoft Teams, Skype for Business Online, SharePoint Online, Azure Rights Management Services or Compliance Center.

All these services use a different PowerShell session, use a different endpoint FQDN, and in some cases require a locally installed PowerShell module. Likely common denominator is the credential used to access each of these services. So, tired of re-entering my credentials every time when switching from Exchange Online to Exchange Online Protection, I created a script with a set of functions to allow me connect to each individual Office 365 service or Exchange Online:

  • Connect-AzureActiveDirectory: Connects to Azure Active Directory
  • Connect-AzureRMS: Connects to Azure Rights Management
  • Connect-ExchangeOnline: Connects to Exchange Online
  • Connect-SkypeOnline: Connects to Skype for Business Online
  • Connect-EOP: Connects to Exchange Online Protection
  • Connect-ComplianceCenter: Connects to Compliance Center
  • Connect-SharePointOnline: Connects to SharePoint Online
  • Connect-MSTeams: Connects to Microsoft Teams
  • Get-Office365Credentials: Gets Office 365 credentials
  • Connect-ExchangeOnPremises: Connects to Exchange On-Premises
  • Get-OnPremisesCredentials: Gets On-Premises credentials
  • Get-ExchangeOnPremisesFQDN: Gets FQDN for Exchange On-Premises
  • Get-Office365Tenant: Gets Office 365 tenant name (SharePoint)
  • Set-Office365Environment: Configures Uri’s and region to use

Note that functions and credentials used in the script are global, and in principle only need to be entered once per shell or ISE session. If you need different credentials, call Get-Office365Credentials again. User interaction is a very basic (Read-Host), but it does the job. The script will also detect if  any PowerShell module supporting Multi-Factor Authentication is installed. If so, you will be prompted if for using MFA when authenticating to workloads such as Exchange Online, Azure Active Directory, Microsoft Teams, Skype for Business Online or SharePoint Online.

Requirements
During initialization, the script will detect the modules which are required for certain Office 365 services. When not installed, it will notify you, and provide a link where to obtain the PowerShell module. The related Connect function will not be made available. PowerShell is required to run this script, which is tested against version 5.1 (but should work with lower versions down to version 3).

Usage
The functions are contained in a script called Connect-Office365Services.ps1. You can call this script manually from your PowerShell session to make the functions available. However, more convenient may be to have them always available in every PowerShell or ISE session. To achieve this, you need to edit your $profile, which is a script which always starts when you start a PowerShell or ISE session. By default this file does not exist and you need to create it, including the path. Also note that the files for PowerShell and ISE are different, Microsoft.PowerShell_profile.ps1
and Microsoft.PowerShellISE_profile.ps1 respectively.

Now, of course you can copy and paste the functions from the script file to your own $profile. Better is to call the script from your $profile, as this allows you to overwrite the Connect-Office365Services.ps1 with updates. To achieve this, assume you copied the Connect-Office365Services.ps1 in the same location as your $profile, for example C:\Users\Michel\Documents\WindowsPowerShell. You can then make PowerShell and ISE call this script by adding the following line to the $profile scripts:

& “$PSScriptRoot\Connect-Office365Services.ps1”

Now when you start a PowerShell session, you might see the following:

cos175

This shows the Microsoft Online Sign-In Assistant and Azure Active Directory PowerShell module is available, and related connect functions should be available.

When you load the script from ISE, it will show something similar. However, it will also show ISE is detected and make all functions available through the Add-On menu:

image

Notes
Customize this script to your liking. Also, by default the script will not perform version checking of installed modules where possible by consulting the PowerShell Gallery, as it slows down loading. If you want this, look up this line and change $false to $true:
$local:OnlineModuleVersionChecks = $false

Download / Revisions
You can download the script from the TechNet Gallery here. The TechNet Gallery page as well as the script contains revision information.

Feedback
Feedback is welcomed through the comments. If you got scripting suggestions or questions, do not hesitate using the contact form.

25 thoughts on “Connecting to Office 365/Exchange

  1. Pingback: IT/DEV Connections 2015 Wrap-Up | EighTwOne (821)

  2. Pingback: Fixing Well-Known Folders Troubles (Update) | EighTwOne (821)

  3. Hi Michel,
    Your script has been a great time-saver for me. I just added the latest version (5/30/17) to my profile and it keeps crashing with the ‘404’ error whenever it tries to load and connect to SkypeOnline. Happens with both the ‘connect-office365’ as well as ‘connect-skypeonline’ calls. The ‘all services’ command doesn’t go any further when it fails at Skype. I’m looking forward to seeing what we can do with the MFA side of this once I get past this. If I’m doing something wrong, pls advise. Thanks!

  4. Thanks, @Michael de Rooij, for your work on this. Huge Time Saver…

    Loaded all the modules but haven’t verified connectivity to each of them yet. Just wanted to let you know that I encountered the following error when initially running version 1.71, May 29nd, 2017

    Write-Warning : Cannot bind parameter ‘ErrorAction’. Cannot convert value
    “https://www.microsoft.com/en-us/download/confirmation.aspx?id=39267&6B49FDFB-8E5B-4B07-BC31-15695C5A2143=1” to type
    “System.Management.Automation.ActionPreference”. Error: “Unable to match the identifier name
    https://www.microsoft.com/en-us/download/confirmation.aspx?id=39267&6B49FDFB-8E5B-4B07-BC31-15695C5A2143=1 to a valid enumerator name. Specify one
    of the following enumerator names and try again:
    SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend”
    At C:\Users\nic7298-nmdev\Documents\WindowsPowerShell\Connect-Office365Services.ps1:276 char:226
    + … ErrorAction ‘https://www.microsoft.com/en-us/download/confirmation.as …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : InvalidArgument: (:) [Write-Warning], ParameterBindingException
    + FullyQualifiedErrorId : CannotConvertArgumentNoMessage,Microsoft.PowerShell.Commands.WriteWarningCommand

    I was able to circumvent the error easily enough by editing the script as follows:
    Line 270 Added $ErrorActionPreference = “SilentlyContinue”
    Line 272 Removed -ErrorAction SilentlyContinue
    Line 278 Added $ErrorActionPreference = “Continue”

    One other minor issue, to get the ADAzurePreview module to load, I had to use the following command.
    Install-Module -Name AzureADPreview -AllowClobber

    • Thanks for the feedback. That message is odd, I’m running the 1.71 myself (with AzureADPreview installed) from w10. You by any chance import the non-preview module as well (since you’re using AllowClobber)?

  5. Hi, I have been using this script for couple of months,
    I redownloaded the script Version 1.71 and I have noticed the “Add-Ons” is not showing up the options, I am using powershell ISE,
    Cheers, Imrul

    • Hold LShift during start up. When you want different behavior, change the line which reads:
      $local:CreateISEMenu = $psISE -and [System.Windows.Input.Keyboard]::IsKeyDown( [System.Windows.Input.Key]::LeftShift)

      to
      $local:CreateISEMenu = $psISE

  6. Hi Michel, thanks for the script! I am now using it with the MultiFactorAuthentication and what I run in to is that when I run the connect function to connect to all, you do not immediately set the $global:Office365CredentialsMFA and thus the AzureAD connection is tried with the basic credentials object. I updated it to initially call that Get-Office365Credentials function that sets the $global:Office365CredentialsMFA, and then that works.

    What is a bit annoying with that MFA in Powershell is that for every connection that you make you need to authenticate again, and as far as I see the compliance-center powershell URI does not (yet) support MFA? Is that correct?
    Thanks for sharing!

    • Thanks for the heads up. Unfortunately, tokens cannot be reused across connecting to workloads atm. And yes, standard PowerShell remoting does no support ADAL (thus MFA), e.g. ‘legacy’ Exchange Online or Compliance Center.

  7. I receive the following error when starting the script:

    Exchange Multi-Factor Authentication PowerShell Module installed (version 16.00.1935.000)
    Import-Module : A parameter cannot be found that matches parameter name ‘FullyQualifiedName’.
    At C:\Users\lholstee\Downloads\Connect-Office365Services.ps1:287 char:17
    + Import-Module -FullyQualifiedName $local:ModuleName -Force
    + ~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : InvalidArgument: (:) [Import-Module], ParameterBindingException
    + FullyQualifiedErrorId : NamedParameterNotFound,Microsoft.PowerShell.Commands.ImportModuleCommand

    any suggestions?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s