Skip to content
Browse

/commands/teams/connect-microsoftteams

Connect-MicrosoftTeams: interactive, device code and certificate (app-only) sign-in

The commands on this page have not been executed by our verification runner yet.updated
tool
Microsoft Teams PowerShell
versions
MicrosoftTeams 8.0.0
os
windows, linux, macos

Connect-MicrosoftTeams from the MicrosoftTeams module opens the session that every Teams cmdlet (Get-Team, Grant-CsTeamsMeetingPolicy, Set-CsPhoneNumberAssignment, ...) needs:

powershell
Install-Module MicrosoftTeams -Scope CurrentUser   # once
Connect-MicrosoftTeams

The command opens a sign-in window (Web Account Manager on Windows) and supports MFA. You need a Teams admin role, such as Teams Administrator, for policy and configuration cmdlets.

Sign-in options

ScenarioCommand
InteractiveConnect-MicrosoftTeams
Pick the accountConnect-MicrosoftTeams -AccountId admin@contoso.com
No browser on this machineConnect-MicrosoftTeams -UseDeviceAuthentication
WAM sign-in problems on WindowsConnect-MicrosoftTeams -DisableWAM
Stored credential (no MFA)Connect-MicrosoftTeams -Credential (Get-Credential)
GCC High / DoD / 21VianetConnect-MicrosoftTeams -TeamsEnvironmentName TeamsGCCH (TeamsDOD, TeamsChina)
App-only with a certificateConnect-MicrosoftTeams -CertificateThumbprint THUMBPRINT -ApplicationId APP_ID -TenantId TENANT_ID
Azure managed identityConnect-MicrosoftTeams -Identity

In module 8.0.0 the certificate parameter set is -TenantId <string> -Certificate <CertificateParameter> -ApplicationId <string>; -CertificateThumbprint is an alias of -Certificate, so both the thumbprint form from Microsoft's examples and an X509Certificate2 object work. You can check it offline:

powershell
Import-Module MicrosoftTeams
$p = (Get-Command Connect-MicrosoftTeams).Parameters
'Certificate aliases:  ' + ($p['Certificate'].Aliases -join ', ')
'Certificate type:     ' + $p['Certificate'].ParameterType.Name
'UseDeviceAuthentication: ' + $p.ContainsKey('UseDeviceAuthentication')
'Identity (managed identity): ' + $p.ContainsKey('Identity')

App-only authentication

Application-based authentication supports only a subset of Teams cmdlets; Microsoft lists them in "Application-based authentication in Teams PowerShell Module". The app needs Microsoft Graph application permissions for the Teams cmdlets it calls and a Microsoft Entra role (for example Teams Administrator) assigned to its service principal for the Cs policy cmdlets.

powershell
Connect-MicrosoftTeams -CertificateThumbprint "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" `
  -ApplicationId "00000000-0000-0000-0000-000000000000" -TenantId "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY"

Check and close the session

powershell
Get-CsTenant | Select-Object DisplayName,TenantId
Disconnect-MicrosoftTeams

A call to a Teams cmdlet without a session fails with Session is not established or You must call the Connect-MicrosoftTeams cmdlet.

Sources

Related pages

errors · teamsSession is not established, run Connect-MicrosoftTeams before requesting access tokenThe Cs cmdlets of the MicrosoftTeams module (Get-CsOnlineUser, Grant-Cs*Policy, Set-CsPhoneNumberAssignment) need a session. Run Connect-MicrosoftTeams first.errors · teamsYou must call the Connect-MicrosoftTeams cmdlet before calling any other cmdlets.Get-Team, New-Team and the other team cmdlets fail with this message when the MicrosoftTeams module has no session. Run Connect-MicrosoftTeams, then retry.commands · teamsGet-Team and New-Team: list and create Microsoft Teams teams with PowerShellGet-Team filters teams by name, user, visibility or archive state; New-Team creates one with -Visibility Public, Private or HiddenMembership. Add members too.flags · teamsConnect-MicrosoftTeams -UseDeviceAuthentication: sign in with a device codeConnect-MicrosoftTeams -UseDeviceAuthentication signs in with a device code from any browser. Works in Windows PowerShell 5.1 too; parameter set and limits.