Boun, What?
Boun-Shell. A portmanteau of Greig Sheriden’s BounSky (pronounced Bounski) and PowerShell

About the Tool

Yeah okay its got a cool name, but what is it?

Well, its a tool to connect you to multiple Office365 tenants simply and easily.

Lync/Skype4B consultants such as myself have been spoiled for years when working with different customers installations thanks to a tool from MVP Greig Sheriden known as BounSky/Profiles for Lync that let us jump from one customer to another for testing.

But as all these customers were homed on premises with different remote access methods, as well as differing security standards, the administration side was no-where near as simple.

With the advent of Office365 and Microsoft Teams I found myself needing to login to the same Office365 service over and over with different tenants, multiple times depending on what I needed to administer. Working with Teams? need the Teams PowerShell module. Working with voice in Skype online or Teams? Need the Skype4BOnline Module. Voicemail? Exchange Module. Did I mention you need to connect to each of these manually?

What if I wanted to compare two tenants to each other? I had to try and keep PowerShell instances separate from each other. That’s a royal pain; and well, Just look at Microsoft screenshot from docs.microsoft.com for connecting to multiple O365 services.

Connect to multiple Office365 Tenants simply and easily

Here’s where BounShell comes in, it allows you to keep a list of different Office365/Microsoft365 Tenants, and connect to them with a couple of clicks or even a keyboard shortcut.

Need to connect to 3 different tenants? No problem.

BounShell will spawn a new tab in the PowerShell ISE and setup all the connections you need. Allowing for multiple concurrent connections. It even keeps global variables separate so you cant accidentally put one customers config into another!

But what if you don’t like the ISE or you use VSCode? I’ve got you covered there too! BounShell is a PowerShell Module and can be called from anything that supports modules. So you could even integrate it into your own scripts if you really wanted. I personally use it with ConEmu. So I can jump into a tenant with just a few keyboard shortcuts!

Once you configure your accounts in the ISE you can call Connect-BsO365Tenant -Tenant 1 from any PowerShell instance and that instance will be connected to your tenant.

BounShell works anywhere PowerShell works!

I use Multifactor (MFA) or ADFS integration, can I still use BounShell?

Yep. Just tell BounShell you’re using Modern Auth when setting up your accounts and it will use the relevant connection strings to kick off Modern Auth.
Dont want to have to type your username and password? It will automatically put it into the clipboard for you (optional).

Worried about your password sitting in the clipboard? BounShell will overwrite the clipboard straight afterwards to make sure you don’t paste it somewhere else.
Don’t want to use that feature at all? That’s fine. You can turn it off in settings.

See it in action here

I like keyboard shortcuts, how do I connect to a tenant quickly?

Simple, if you’re using the PowerShell ISE, BounShell automatically registers Ctrl+Alt+1 through to Ctrl+Alt-0 for tenants 1 through 10

So as long is BounShell is loaded, either by running Start-BounShell, or adding it you your PowerShell profile script, you can press Ctrl+Alt+3 to connect to start a new tab and then connect to tenant 3.

More of a keyboard warrior? Don’t like the ISE? Or don’t want to load BounShell first?
That’s fine! Simply run Connect-Bso365Tenant -Tenant 3 and BounShell will open a new tab (in the ISE only) and connect to tenant 3 using your stored creds.
Can’t remember which tenant it was? Run Connect-Bso365Tenant and BounShell will display a menu of configured tenants.

Using ConEmu? Press Ctrl+~ to bring up your shell and run Connect-Bso365tenant Boom. Connected.

This sounds great, but what about security?

BounShell uses the ConvertTo-SecureString encryption method built into PowerShell before storing your credentials in your User Profile folder.
This is the same cmdlet used by Get-Credential and many of the other Office365 cmdlets to keep a password secure in memory or on disk.
The BounShell XML file contains these credentials in their SecureString format, and unless we need to use ModernAuth, we don’t ever decrypt it again.
We also don’t write any of your passwords to log files, so they are safe to send in for troubleshooting.

Using ModernAuth? We make sure we clear the clipboard as soon as you paste the user password so you wont paste it somewhere else by mistake. You can even stop BounShell from putting your passwords in the clipboard and type them manually.

Worried about your credentials at rest? BounShell uses the Windows Data Protection API (DPAPI) ,along with your user profiles AES encryption key, to ensure only you can read your credentials.

BounShell is also written in PowerShell itself. So there’s no compiled code. No obfuscation. No installer. You can see exactly what is doing what with your credentials.

Add to that BounShell is completely free and open source under the MIT Licence, so you can go grab the code from GitHub and check it for flaws yourself.

How confident am I in BounShell’s credential encryption? Here’s my demo account creds stored as a secure string from my BounShell.xml and the relevant article on docs.microsoft.com to get you started

01000000d08c8ddf0115d1118c7a00c04fc297eb010000009fbc4080ab4cd1449efd9a1db117dfb70000000002000000000003660000c00000001000000047e64b90d71dca0d657998d6ce463ed10000000004800000a0000000100000000bbdca97f08396a530a4b970c07dc68330000000a1cdca905bc5d8dfb8594b577b1468b8287eae2534a9d5de837151bcec5a5efeba712202354630bd139a05907af118b8140000009004f0c61c47087435544b6717f1d8ebe0d0d220

Note: None of this excuses you from your own basic security. No encryption system is foolproof. Ensure all your accounts are using MFA, don’t download anything dodgy and keep your BounShell.xml file safe! I cant be held responsible if someone steals your creds!

Known Bugs?

I’m not going to lie. No software is perfect.

There is currently a known issue with both the Exchange Online Module and The Skype Online module, where if they are left to idle after authenticating using MFA, they can hang the ISE.
This is a known issue of the modules themselves and not the fault of BounShell. See the following UserVoice thread.

Installation / Download

Installation of BounShell is simple.

Method one

Use NuGet to automatically install it from the PowerShell gallery.

Install-Module -Name BounShell

Method two

Grab the code from GitHub and install it in your modules folder: (C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules or C:\Program Files\WindowsPowerShell\Modules by default)

https://github.com/Atreidae/BounShell

Method three

Wanna try the bleeding edge and not have beta code sitting in your modules folder? Maybe develop your own fork?

Clone the dev branch from github and add the githib repo to your modules path.

#Clone the repo
git home https://github.com/Atreidae/BounShell.git c:\github\Bounshell
#Open the all users profile
notepad $profile.AllUsersAllHosts
#And add the following line
$env:PSModulePath = $env:PSModulePath + ";c:\github\" 
#Save and restart PowerShell

First Run and Inital Setup

Now that BounShell is installed, kick it off by running Start-BounShell in your PowerShell window.

If you’re using the ISE. Click Add-ons > BounShell > Settings to bring up the tenant configuration. Otherwise run the cmdlet Show-BsGuiElements for the same effect.

Any time you update your tenant settings, BounShell will check for a newer version of any relevant PowerShell modules from the PSGallery and prompt you if you want to install them.

If you want to install these manually for any reason. Run the following from an elevated (admin) PowerShell window.

#Install the modules
Install-Module -name MSOnline, MicrosoftTeams, Microsoft.Online.SharePoint.PowerShell, ExchangeOnlineShell, AADRM
#You should also run update-module to update anything thats already installed
Update-Module -name MSOnline, MicrosoftTeams, Microsoft.Online.SharePoint.PowerShell, ExchangeOnlineShell, AADRM

Acknowledgements

Inspiration for this tool came from Greig Sheriden’s wonderful Bounsky tool and a nudge from one of my Co-Workers Justin O’mera

Thanks to Pat Richard, Greig Sheriden (again) and Shane Hoey for really getting me writing good modular code. Beer is on me at some point.

Thanks to Don Jones and his “Learn PowerShell in a month of lunches” without which I never would be writing the code I am today

Module installer functions based on code from Andrew Price’s Detect-MicrosoftTeams-Version script. Used with Permission

All code built completely in the PowerShell ISE using ISE-Steroids. Thanks to Dr. Tobias Weltner for the tool and IComm for the licence. Visit PowerTheShell.com for a free trial.

WinForms Gui written in VisualStudio (free) using Fox-Deploys fantastic guide, I may port it to WPF at some point.

My Employer IComm Australia for supporting all my extra curricular activities and providing licences for tools to help me write better code for all of you.

To the whole Office365 MVP community, especially the Teams and UC guys. “Change is the only constant!”

Thanks To my Wife Sarah for constantly reminding me to work on this instead of playing Destiny.