Sunday, 29 January 2017

One shell to rule them all

Or, how to connect to multiple services such as Exchange Online, Local Exchange, SharePoint Online, Azure and more from a single PowerShell Session.
[Edited on 2017/02/21 to account for changes in Azure Module distribution]


I wanted to be able to manage all services from a single PowerShell session, and after searching around, I found this article which is quite a nice way to start. However, since I always try to cut on repetitive tasks, it wasn’t long until I considerably changed that process so as to have it all ready by simply executing one command and avoiding logins by storing them safely in my machine. Not only that, but the need to add some more modules, like Azure related ones, had me expanding on that article a lot.


By following the instructions below, you’ll be able to connect to one or more (or all!) of the following services in a single PowerShell session:
  1. Microsoft Online (aka: Office 365 user management);
  2. Exchange Online (aka: Office 365 mailboxes/groups);
  3. Security and Compliance Centre;
  4. SharePoint Online;
  5. Skype Online (aka: Skype For Business);
  6. Azure (both Service Management and Resource Manager models);
  7. On Premises Exchange.
You can add more to the list, the functions are all laid out in an easy to follow format. I could have condensed them and cut considerably on code repetition, but I think they are more readable this way.

Installing the required software

Pre-Windows 10 - requires at least PowerShell 3.0, but if you can, just go all the way to 5.1 with the following links:
.NET Framework 4.5+ (I tested with 4.6.2 on Windows 7 SP1 x64)
Windows Management Framework 5.1  (Reboot to continue)

All 64 bit platforms with at least PowerShell 3:
Requires downloading some installers to execute on the machine, so, let’s start with that. Download and install all of the following:
Microsoft Online Service Sign-in Assistant for IT Professionals RTW
Windows Azure Active Directory Module for Windows PowerShell (64-bit version)
SharePoint Online Management Shell
Skype for Business Online, Windows PowerShell Module

Now launch PowerShell ISE as Administrator and run the following commands:
Set-ExecutionPolicy RemoteSigned –Force
Install-Module Azure -Force
Install-Module AzureRM -Force
You'll have to answer Yes to a couple prompts for the second command, and it's ok to see an error complaining of commands overwriting similar named commands in other modules: the Azure team is working on that, but for now just ignore if it still happens when you follow this procedure.

Download the following files from this github repo:
Services.psd1 – Contains settings that you MUST change!
Common.ps1 – Main file with the required functions
These files will go to the same folder as your PowerShell profile (type $profile to find out where it is).
You will need to add the following line to your $profile (create one if you have none already, otherwise add to the end):
Get-ChildItem ([Environment]::GetFolderPath("MyDocuments")+"\WindowsPowerShell\Common.ps1") `
-ErrorAction SilentlyContinue |% { .$_ }
(You can add it in a single line: broken here for clarity. Remove the “`” if you place all in a single line)
Note: SharePoint Online, Azure and Skype Online modules will require that you run PowerShell as Admin, so the easiest way is to change your PowerShell shortcut to run in admin mode. You’ll get a clear error if trying to execute the functions in a “normal” PowerShell session.
Don’t forget to edit the Services.psd1 file! There are at least 9 places that you need to edit, all marked with [ and ] (remove the brackets after replacing the placeholders with the proper values, e.g., suppose your online login is – where you have:
    Login  = "[login@yourtenant]";
You should edit to:
    Login  = "";
After that, whenever you launch PowerShell, you should see this:
This is a reminder to let you know what functions you have available. If you wish to connect to ALL, just run Connect-SvcAll
When you do, you’ll get something like this:
The first warning reminds you to run the command:
Save-EncriptedCredentials -UserPrincipalName
This will prompt you for the password for that account and will store it encrypted in a file in your home folder. Should this file be moved to another computer it will NOT work. You will notice some more warnings about the same thing – that’s because you probably use the same login in multiple services – you only need to run the above command ONCE for each unique login.

The second warning tells you that loading the Azure module was skipped because you’re not running PowerShell as Administrator, so you know what to do to fix that.

After you enter all the needed credentials and run the commands again in a properly elevated PowerShell, you’ll see something like this (assuming you did everything right: if you didn’t, you’ll probably get a nice warning giving you a hint on what went wrong):
Note: in the above screenshot I did not have a valid local exchange to test, so I intentionally did not enter the credentials.

I’ve added some extra code to start WinRM when connecting to Skype Online as it would stop and prompt me to do so, and to stop the service upon closing down PowerShell, if it was started in that session. If you don’t want that to happen for some reason, just edit the Connect-SvcSkypeOnline function and search for WinRM and remove all the lines.

Optionally, you may want to install the following extra modules and ISE AddOns if you're working with RunBooks:

Install-Module AzureAutomationAuthoringToolkit -Scope CurrentUser
Install-Module ISEScriptAnalyzerAddOn

Finally, if you find this useful, feel free to spread the word. Also feel free to suggest improvements and/or bug fixes.

No comments:

Post a Comment