In June 2020, Microsoft released into preview new functionality in the Microsoft Teams PowerShell module to connect to Skype for Business Online. Prior to this being added, there were two modules required to manage Microsoft Teams and Skype for Business Online: the Skype for Business Online Windows PowerShell module and the Microsoft Teams module. In this post, I’m going to cover how to remove the Skype for Business Online Connector module, install the preview version of the Microsoft Teams module, and the differences in connecting to Skype for Business Online using PowerShell 5.1 and 7.

A Bit of History

Let’s cover some history of these two modules. First, the SkypeOnlineConnector module came first with the release of Skype for Business Online (formerly Lync Online). As of version 7.0.0.0, this module has two functions and three cmdlets:

  • Function: New-CsOnlineSession
  • Function: Enable-CsOnlineSessionForReconnection
  • Cmdlet: Get-CsOnlinePowerShellAccessInformation
  • Cmdlet: Get-CsOnlinePowerShellAccessToken
  • Cmdlet: Get-CsOnlinePowerShellEndpoint

The two functions are of primary interest and used for making connections to you Skype for Business Online tenant. We use the New-CsOnlineSession function to create a remote PowerShell session to Skype for Business Online. We import that session using Import-PSSession. This session downloads a module prefixed with “tmp” that contains the remaining commands to manage the service.

This model allows for adding new commands without releasing and installing a new module. Instead, the new commands are downloaded through the “tmp” module when the remote session is created. However, you can only download the module and install it manually using an MSI. It is not available for installation from the PowerShell Gallery.

After Microsoft Teams came around, it eventually got its own PowerShell module. It is installable from the PowerShell Gallery:

Install-Module -Name MicrosoftTeams

This module first included basic commands around Teams and user management.

However, the Skype for Business Online continued to receive new Teams commands (often designated in the commands with “CsTeams”). The older Skype module is still needed to manage some settings while this second Teams module gains additional functionality.

Merging the Modules

Back in the What’s New in Microsoft Teams | June 2020 edition, Microsoft had this blurb that the Skype for Business Online Connector commands will be consolidated into the Teams module:

While this was later removed from the blog post, this is outlining that they are taking commands from the Skype Online PowerShell module and putting them into the Teams module. You still need to use the New-CsOnlineSession* command to make the remote PowerShell session and import it, but at least you only need to install one module.

However, the module version 1.1.3 is currently in preview and this generally means it is not recommended for production use.

Configuring the Modules

In order to use this preview module with the merged commands, we first need to uninstall the Skype for Business Online Connector module that was installed using an MSI.

To remove the module, you can go into Add/Remove programs, find the installed module, and uninstall it like any other program on the computer:

Uninstall the Skype for Business Online PowerShell module in Add/Remove Programs
Uninstall the Skype for Business Online PowerShell module in Add/Remove Programs

You will not be able to use the Uninstall-Module command to remove the package in PowerShell as the package was not installed using the Install-Module command.

Next, we need to remove the current version of the Microsoft Teams PowerShell module so we can install the preview version. Since this package was installed from the PowerShell Gallery, we can use this command to remove all versions of the module:

Uninstall-Module -Name MicrosoftTeams -AllVersions

Once the module is removed, we can install the preview version using the following command:

Install-Module MicrosoftTeams -AllowPrerelease -RequiredVersion "1.1.3-preview"

If the preview version changes in the future, be sure to update the code to reflect the new version. You can see which versions are in preview by looking at the version history of the module in PowerShell Gallery:

Viewing module version history
Viewing module version history

If you select the link for the version, it will also provide the exact command to install the module:

Exploring the Preview Module

With the preview module installed, we can view the available functions and cmdlets using this line of PowerShell code:

Get-Command -Module MicrosoftTeams

Looking through the list, we’ll see the familiar New-CsOnlineSession cmdlet available. We still need to create the session and import it, but at least the command to do so is in the same module as other Teams commands.

Notably missing is the Enable-CsOnlineSessionForReconnection. This helped create new sessions when the previous one timed-out after 60 minutes.

The process for connecting to Skype for Business Online is largely unchanged in PowerShell 5.1. We need to create the session and import this session. We can pass it a PSCredential object with the username and password, or just run the command and it will prompt for credentials. Once completed, we see the familiar “tmp” module imported with our commands.

$skype = New-CsOnlineSession
Import-PSSession -Session $skype
Connecting to Skype for Business Online in PowerShell 5.1
Connecting to Skype for Business Online in PowerShell 5.1

Compatibility with PowerShell 7

Up until this point, the Skype for Business Online module did not work in PowerShell 7 when creating the remote Skype session. This is due to the module not being .NET Core compatible (I opened an issue for it back in November 2019). I believe I even tried using the Windows compatibility mode but still a no go. Microsoft even warns that the Teams module has known issues in PowerShell 7:

Microsoft Docs warning about PowerShell 7 and the Teams module.
Microsoft Docs warning about PowerShell 7 and the Teams module.

However, the New-CsOnlineSession in the Teams module does work inside of PowerShell 7, and it uses a new way to authenticate. Let’s try to create a new remote session:

$skypePS7 = New-CsOnlineSession
Creating Skype Online remote session in PowerShell 7
Creating Skype Online remote session in PowerShell 7

We get a warning message that we need to navigate to https://microsoft.com/devicelogin and enter the code to authenticate. This is the same process if you are signing into a Teams phone, and I believe the Azure CLI module performs the same type of authentication.

After navigating to that URL, the site will prompt for the code from the PowerShell window. It will then ask for credentials or verify which account to use.

Back in the PowerShell 7 window, there will be a flurry of output showing a token being requested, created, and stored in the cache. If we examine the output, we’ll see the token is good for 1 hour after its creation.

Access token returned
Access token returned

From here, we continue like we always have and import the session:

Import-PSSession -Session $skypePS7

Like the older Skype Online Connector module, it will import a “tmp” with all our familiar commands.

When the access token expires in an hour, the next command we run will prompt for an oauth password. I’ve tried entering my admin account password but it doesn’t like this very much. We can also see that the PSSession is broken:

PSSession Credential Prompt after access token expiration
PSSession Credential Prompt after access token expiration

From here, I decided to re-run the New-CsOnlineSession command from earlier, and this time it does not require me to authenticate. You will see in the output that a refresh token was used instead. After I create the session, I run Import-PSSession with the -AllowClobber parameter. This will allow duplicate commands already imported from the first “tmp” module.

$skypePS7 = New-CsOnlineSession
Import-PSSession -Session $skypePS7 -AllowClobber

Conclusion

Adding the New-CsOnlineSession command into the Teams module is a great step in simplifying the modules for managing both services. However, you still have to make two connections, one using Connect-MicrosoftTeams and another using New-CsOnlineSession. Microsoft continues to add commands for administering Teams policies in the Skype Online module. This makes me cautious that it will be a long time before there is a unified module for managing Teams.

References:
Microsoft Docs: Microsoft Teams PowerShell Overview
Microsoft Docs: Microsoft Teams PowerShell Release Notes
Microsoft Docs: Install Microsoft Teams PowerShell
PowerShell Gallery: Microsoft Teams

Check out my related article on troubleshooting errors connecting to Skype for Business Online PowerShell.

Questions or comments? If so, drop me a note below or find me on Twitter or LinkedIn to discuss further.

Leave a Reply