Connect-MicrosoftTeams

The Connect-MicrosoftTeams cmdlet connects an authenticated account for use with cmdlets from the MicrosoftTeams module.

Syntax

Connect-MicrosoftTeams
       [-TenantId <String>]
       [-Credential <PSCredential>]
       [-AccountId <String>][-LogLevel <LogLevel>]
       [-LogFilePath <String>]
       [-TeamsEnvironmentName <String>]
       [-WhatIf]
       [-Confirm][<CommonParameters>]
Connect-MicrosoftTeams
       -TenantId <String>
       -CertificateThumbprint <String>
       -ApplicationId <String>
       [-LogLevel <LogLevel>]
       [-LogFilePath <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-MicrosoftTeams
       [-TenantId <String>]
       -AccessTokens <String[]>
       [-LogLevel <LogLevel>]
       [-LogFilePath <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Description

The Connect-MicrosoftTeams cmdlet connects to Microsoft Teams with an authenticated account for use with cmdlets from the MicrosoftTeams PowerShell module. After executing this cmdlet, you can disconnect from MicrosoftTeams account using Disconnect-MicrosoftTeams.

Note: With versions 4.x.x or later, enablement of basic authentication is not needed anymore in commercial environments. For GCC High/DoD environments and customers that are, or have previously been enabled for Regionally Hosted Meetings in Skype for Business Online, basic authentication needs to be enabled for *-Cs cmdlets to function properly.

Examples

Example 1: Connect to MicrosoftTeams

This example connects to an Azure account. You must provide a Microsoft account or organizational ID credentials. If multi-factor authentication is enabled for your credentials, you must log in using the interactive option.

Connect-MicrosoftTeams
Account                 Environment    Tenant                                TenantId                         
-------                 -----------  ------------------------------------  ------------------------------------
user@contoso.com        AzureCloud   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example 2: Connect to MicrosoftTeams

The first command prompts for user credentials and stores them in the $Credential variable. The second command connects to an Azure account using the credentials stored in $credential. This account authenticates with Azure using organizational ID credentials.

$credential = Get-Credential
Connect-MicrosoftTeams -Credential $credential
Account                 Environment    Tenant                                TenantId                         
-------                 -----------  ------------------------------------  ------------------------------------
user@contoso.com        AzureCloud   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example 3: Connect to MicrosoftTeams in a specific environment

This example connects to an Azure account in a specific environment. You must provide a Microsoft account or organizational ID credentials. If multi-factor authentication is enabled for your credentials, you must log in using the interactive option.

Connect-MicrosoftTeams -TeamsEnvironmentName TeamsGCCH
Account                 Environment    Tenant                                TenantId                         
-------                 -----------  ------------------------------------  ------------------------------------
user@contoso.com        TeamsGCCH   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example 4: Connect to MicrosoftTeams using a certificate thumbprint

This example demonstrates how to authenticate using a certificate thumbprint. Application-based authentication has been reintroduced with version 4.7.1-preview. For details and supported cmdlets, please see Application-based authentication in Teams PowerShell Module.

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

Example 5: Connect to MicrosoftTeams using Application-based Access Tokens

This example demonstrates how to authenticate with an application using Access Tokens. Access Tokens can be retrieved via the login.microsoftonline.com endpoint. It requires two Access Tokens: "MS Graph" and "Skype and Teams Tenant Admin API" resources.

Application-based authentication has been reintroduced with version 4.7.1-preview. For details and supported cmdlets, see Application-based authentication in Teams PowerShell Module.

$ClientSecret   = "..."
$ApplicationID = "00000000-0000-0000-0000-000000000000"
$TenantID = "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY"

$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")

Example 6: Connect to MicrosoftTeams using Access Tokens in the delegated flow

This example demonstrates how to sign in using Access Tokens. Admin can retrieve Access Tokens via the login.microsoftonline.com endpoint. It requires two tokens, MS Graph Access Token and Teams Resource token.

A delegated flow, such as Resource Owner Password Credentials (ROPC) or device code, must be used, with the following delegated app permissions required.

API Grant type Permission
Microsoft Graph Delegated User.Read.All
Microsoft Graph Delegated Group.ReadWrite.All
Microsoft Graph Delegated AppCatalog.ReadWrite.All
Skype and Teams Tenant Admin API Delegated user_impersonation
$ClientID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$ClientSecret = "..."
$ClientSecret = [Net.WebUtility]::URLEncode($ClientSecret)
$TenantID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$Username = "user@contoso.onmicrosoft.com"
$Password = "..."
$Password = [Net.WebUtility]::URLEncode($Password)

$URI = "https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token"
$Body = "client_id=$ClientID&client_secret=$ClientSecret&grant_type=password&username=$Username&password=$Password"
$RequestParameters = @{
  URI = $URI
  Method = "POST"
  ContentType = "application/x-www-form-urlencoded"
}
$GraphToken = (Invoke-RestMethod @RequestParameters -Body "$Body&scope=https://graph.microsoft.com/.default").access_token
$TeamsToken = (Invoke-RestMethod @RequestParameters -Body "$Body&scope=48ac35b8-9aa8-4d74-927d-1f4a14a0b239/.default").access_token
Connect-MicrosoftTeams -AccessTokens @($GraphToken, $TeamsToken)

Account                 Environment    Tenant                                TenantId                         
-------                 -----------  ------------------------------------  ------------------------------------
user@contoso.com        AzureCloud   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Parameters

-AadAccessToken (Removed from version 2.3.2-preview)

Specifies a Azure Active Directory Graph access token.

Warning

This parameter has been removed from version 2.3.2-preview.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-AccessTokens

Specifies access tokens for "MS Graph" and "Skype and Teams Tenant Admin API" resources. Both the tokens used should be of the same type.

  • Application-based authentication has been reintroduced with version 4.7.1-preview. For details and supported cmdlets, see Application-based authentication in Teams PowerShell Module.

  • Delegated flow - The following steps must be performed by Tenant Admin in the Azure portal when using your own application.

    Steps to configure the AAD application.

    1. Go to Azure portal and go to App Registrations.
    2. Create or select the existing application.
    3. Add the following permission to this Application.
    4. Click API permissions.
    5. Click Add a permission.
    6. Click on the Microsoft MS Graph, and then select Delegated Permission.
    7. Add the following permissions: "AppCatalog.ReadWrite.All", "Group.ReadWrite.All", "User.Read.All";
    8. Next, we need to add "Skype and Teams Tenant Admin API" resource permission. Click Add a permission.
    9. Navigate to "APIs my organization uses"
    10. Search for "Skype and Teams Tenant Admin API".
    11. Add all the listed permissions.
    12. Grant admin consent to both MS Graph and "Skype and Teams Tenant Admin API" name.
Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-AccountId

Specifies the ID of an account.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationId

Specifies the application ID of the service principal that is used in application-based authentication.

This parameter has been reintroduced with version 4.7.1-preview. For more information about Application-based authentication and supported cmdlets, see Application-based authentication in Teams PowerShell Module.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-CertificateThumbprint

Specifies the certificate thumbprint of a digital public key X.509 certificate of an application that has permission to perform this action.

This parameter has been reintroduced with version 4.7.1-preview. For more information about Application-based authentication and supported cmdlets, see Application-based authentication in Teams PowerShell Module.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

Specifies a PSCredential object. For more information about the PSCredential object, type Get-Help Get-Credential.

The PSCredential object provides the user ID and password for organizational ID credentials.

Type:PSCredential
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Identity

Login using managed service identity in the current environment. This is currently not supported for *-Cs cmdlets.

Type:SwitchParameter
Aliases:MSI, ManagedService
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-LogFilePath

The path where the log file for this PowerShell session is written to. Provide a value here if you need to deviate from the default PowerShell log file location.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-LogLevel

Specifies the log level. The acceptable values for this parameter are:

  • Info
  • Error
  • Warning
  • None

The default value is Info.

Type:LogLevel
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ManagedServiceHostName

Host name for managed service login.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ManagedServicePort

Port number for managed service login.

Type:Int32
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ManagedServiceSecret

Secret, used for some kinds of managed service login.

Type:SecureString
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-MsAccessToken (Removed from version 2.3.2-preview)

Specifies a Microsoft Graph access token.

Warning

This parameter has been removed from version 2.3.2-preview.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TeamsEnvironmentName

Use this setting if your organization is in one of the Teams Government Cloud environments.

Specify "TeamsGCCH" if your organization is in the GCC High Environment. Specify "TeamsDOD" if your organization is in the DoD Environment.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TenantId

Specifies the ID of a tenant.

If you do not specify this parameter, the account is authenticated with the home tenant.

You must specify the TenantId parameter to authenticate as a service principal or when using Microsoft account.

Type:String
Aliases:Domain, TenantDomain
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False