Teams PowerShell Module – Token Authentication

There are several ways to get the Teams PowerShell module to authenticate against Azure in order to get access to running Teams PowerShell in your Tenancy. Most people will be used to using the interactive method where you just run the basic Connect-MicrosoftTeams command and get an interactive Azure auth screen that pops up and you enter your user account details into. This is fine if you are manually connecting and doing this by hand. However, what if you want to run an Azure Function that needs to authenticate automatically each time it executes? Well, for that you want to use an application authentication method.

Currently as of the module version 4.9.1, Microsoft officially supports two methods for application authentication when connecting to the Teams PowerShell module:

• Token based authentication – The token-based method requires that you set up a Client Secret in Azure. When you connect to Azure using the PowerShell module, you authenticate against the Token Service using the Client Secret and get Tokens back that you can use to connect to the service. We will dig further into this method in this post.
• Certificate based authentication – In this method you have a certificate with private and public keys. The PC connecting to Azure needs to have a copy of the private key and Azure needs to have a stored copy of the public key. As part of the connection, the private key will be used to sign the connection and if Azure can decrypt the information with the public key, then the PC is trusted to connect. This essentially makes the private key like a password that you need to ensure that no one else has access to. If you would like to know more about this method, please check out my post here about it: Certificate Auth Post.

In this post we are going to focus on the token-based authentication method. Here are the steps for setting up and connecting using token-based authentication:

 

Step 1: Configure the App Registration:

Open the Azure AD Portal and select the Azure Active Directory > App Registration section:

 

Click the New Registration Button:

 

Fill in a name for the application and click the Register button:

 The App Registration will now be created. However, there is still more config to do:

Go to the “Certificates & secrets” blade:

Enter a name for your client secret that makes sense for you and click "Add":

You will now seen your new Client Secret. Copy the secret value and put it somewhere safe:

I'll say it again, before leaving this screen take a copy of the Client Secret Value because it will not be available when you return later. Also, it’s important that you treat this secret as you would a password because it can give anyone the keys to your Teams castle… which would be very bad.

 

Configure the Application Permissions:

You will need to add the following Graph API permissions to the App Registration:

User.Read.All

Group.ReadWrite.All

AppCatalog.ReadWrite.All

TeamSettings.ReadWrite.All

Channel.Delete.All

ChannelSettings.ReadWrite.All

ChannelMember.ReadWrite.All

These permissions are documented by Microsoft here, so you may want to check to see if there have been any updates for the PowerShell version you're using: https://learn.microsoft.com/en-us/microsoftteams/teams-powershell-application-authentication

 

Click the "Microsoft Graph" option:

Select "Application Permissions":

Select the permissions that were listed above:

Ensure that you have added all the permissions. If you missed any then repeat the above steps for all the permissions in the list…

 

After adding all the permissions you need to click the “Grant admin consent for <tenant id>” button on the main Permissions screen:

At the end of this procedure you should have the following permissions all assigned with admin consent granted:

 

In a final twist in this adventure, you also need to make sure you assign Teams Administrator privileges to the App Registration in order for it to be able to run CS commands. You do this by going to the Active Directory tab > Roles and Administrators > Teams Administrator Role:

 

Assign the Service Permission that is named the same as your App Registration to the RBAC Role:

 

Connecting To Teams PowerShell

 

Now that all the backend work has been done, we can get down to doing some connecting.

You will need to know the ApplicationId that was given to the App Registration in Azure. You can find this out by looking going to the Overview tab and looking for the GUID that has the title “Application (client) ID”. The TenantId is the base domain name that was first given to your tenancy when it was created or alternatively can be the GUID that’s in the Overview tab named as “Directory (tenant) ID” (both options will work). And you need to know the Client Secret that was created at the beginning of the App Registration creation process (I did tell you to take note of this -- if you didn’t then you may not be able to see the secret in the portal anymore. If so, then you need to create a new one).

  

The Connection PowerShell:

$ClientSecret   = "P_1a3~cNhA1Jd~iS9.mdUh2ffe_qp~u9Leuk4aYa" # Your Client Secret

$ApplicationID = "00000000-0000-0000-0000-000000000000" #Your Application ID

$TenantID = "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY" #Your Tenant ID

 

$graphtokenBody = @{  

   Grant_Type    = "client_credentials"  

   Scope         = "https://graph.microsoft.com/.default"  

   Client_Id     = $ApplicationID  

   Client_Secret = $ClientSecret  

} 

 

$graphToken = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token" -Method POST -Body $graphtokenBody | Select-Object -ExpandProperty Access_Token

 

$teamstokenBody = @{  

   Grant_Type    = "client_credentials"  

   Scope         = "48ac35b8-9aa8-4d74-927d-1f4a14a0b239/.default"

   Client_Id     = $ApplicationID  

   Client_Secret = $ClientSecret

}

 

$teamsToken = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token" -Method POST -Body $teamstokenBody | Select-Object -ExpandProperty Access_Token

 

Connect-MicrosoftTeams -AccessTokens @("$graphToken", "$teamsToken")

 

I know what you’re thinking… That’s a lot of PowerShell code to just connect to PowerShell and you are correct in thinking that. However, this code, while looking ominous, is actually not all that complicated when you break it down.

Let’s break it down; The first 3 lines are variables where you need to fill in your specific Secret, Application ID and Tenant ID. These are the only three lines that you need to edit, so you can relax. The other lines of code basically run two separate REST calls to Azure to get access to two different tokens. One token is for the Graph API and the other is for Teams. Once you have these tokens you then pass them to the Connect-MicrosoftTeams command which uses them to authenticate against the service.

Note: The tokens have a lifetime of 1 hour, so if you were going to make an app that was going to make a lot of connections over the course of an hour you make want to cache the tokens and reuse them.

When connection is successful, you’ll get back an object displayed in the PowerShell window that tells you the Account, Environment, Tenant and TenantId values. From here you should be able to run almost all of the commands from the module, with the following exclusions:

As of 4.9.1; All cmdlets are supported now, except for the cmdlets mentioned below:

• New-Team
• [Get|Set|New|Sync]-CsOnlineApplicationInstance
• *-CsUserCallingSettings
• *-CsUserCallingDelegate
• *PolicyPackage*
• *-CsTeamsShiftsConnection*
• *-CsBatchTeamsDeployment*

The Wrap Up

 

There’s all you should hopefully need to know about setting up a simple Token Authentication based connect to Microsoft Teams PowerShell. At the beginning of the post I also mentioned Certificate-based authentication. If you would like to know more about Certificate-based authentication, don’t forget you can check out my post here about it: Certificate Auth Post.