PnP Teams Cmdlets - How to connect

2020-07-13 4 min read

Starting with the July 2020 release of PnP PowerShell we added quite a series of new cmdlets focusing on Microsoft Teams.

Why did we release our own cmdlets, if there are already Microsoft Teams cmdlets out there? Well, we’ve heard from the community that they prefer to have only one cmdlet module installed, not having to learn different ways to connect to the environment, and in general have more control (by means of pull requests, and the fact that the code is open source) on what the cmdlets do.

In this post I will talk not in specific details on what the cmdlets do or how to use them, you can simply look at the help online https://docs.microsoft.com/en-gb/powershell/module/sharepoint-pnp/?view=sharepoint-ps or check out the built-in help :

Get-Help *-PnPTeams*

This will list all cmdlets. Ask for help for a specific cmdlet:

Get-Help Get-PnPTeamsTeam -Detailed

Every Teams (and Graph related) cmdlet will list which permissions it needs:

The cmdlets

* Add-PnPTeamsChannel
* Add-PnPTeamsTab
* Add-PnPTeamsTeam
* Add-PnPTeamsUser
* Get-PnPTeamsApp
* Get-PnPTeamsChannel
* Get-PnPTeamsChannelMessage
* Get-PnPTeamsTab
* Get-PnPTeamsTeam
* Get-PnPTeamsUser
* New-PnPTeamsApp
* New-PnPTeamsTeam
* Remove-PnPTeamsApp
* Remove-PnPTeamsChannel
* Remove-PnPTeamsTab
* Remove-PnPTeamsTeam
* Remove-PnPTeamsUser
* Set-PnPTeamsChannel
* Set-PnPTeamsTab
* Set-PnPTeamsTeam
* Set-PnPTeamsTeamArchivedState
* Set-PnPTeamsTeamPicture
* Submit-PnPTeamsChannelMessage
* Update-PnPTeamsApp

The PnP PowerShell cmdlets use the Microsoft Graph API to community with the Teams instances. This means that you will have to connect in a different way.

Let’s go through a few of the connection options:

Option 1: easy

Connect-PnPOnline -Scopes “Group.ReadWrite.All” This option will launch a popup window and it will ask you to authenticate. If you have never done this before, you could be asked to provide consent. What is happening is that an app id is added to your Azure AD. This app is registered by the PnP Team and is called “PnP Management Shell”. It is used by both PnP PowerShell and the Office 365 CLI. You can find the app if you navigate to your Azure portal, open the Azure AD and go to “Enterprise Apps”. In there you can find the PnP Management Shell and see exactly what consent you have done. It’s there where you also can remove the app from your Azure AD.

Option 2: A bit more complex

Connect-PnPOnline -Scopes “Group.ReadWrite.All” -Credentials (Get-Credential) This will first popup a dialog where you enter a username and password. Then a request is made to the Azure AD for a so-called delegate token. This means that you will act towards Teams under the username of the user you specified. The nice part about authenticating this way is that you can use a little trick to automate the credentials:

Add-PnPStoredCredential -Name "MyCredential" -Username your@username.com

You will be asked to enter a password. PnP PowerShell will now create an entry in the Windows Credential Manager. You can remove this entry if you want by using Remove-PnPStoreCredential -Name “MyCredential”, or open the Credential Manager from your control panel and manually remove the entry there.

The moment the entry is in place you can connect using:

Connect-PnPOnline -Scopes "Group.ReadWrite.All" -Credentials "MyCredential"

PnP PowerShell will then check the credential manager if there is an entry called “MyCredential”. If so it will use the credentials associated by that entry.

Option 3: Using a device code

Connect-PnPOnline -Graph -LaunchBrowser

Using this option you will see a popup where you can enter a one-time use code. This code has been automatically copied to your clipboard, so you can simply paste the code in the field. Confirm, enter your username and password and you’re connected.

Other options

There are more ways to connection:

Using a clientid and secret or by using a clientid and certificate. For both options you will first need to register your own application in your Azure AD. The easiest way to do that is by using the Initialize-PnPPowerShellAuthentication cmdlet. Check the detailed help of this cmdlet for it’s use:

Get-Help Initialize-PnPPowerShellAuthentication -Detailed