Maintaining your Teams Connector deployment

After you have installed and configured your Teams Connector there are several maintenance tasks you may need to perform, such as adding extra Conferencing Nodes, changing your call capacity or upgrading the platform to the latest software version.

Modifying the Teams Connector's configuration

If you need to change the configuration on the Teams Connector after it has been deployed, you must make the necessary changes to the variables in your initialization script and then redeploy it using the new configuration, as described below. Configuration changes that require redeployment include:

  • Changing the pool name or node FQDNs of the associated Conferencing Nodes (the name referenced by the $PxNodeFqdns variable in the initialization script).
  • Enabling RDP access to the Teams Connector instances (from any addresses specified in the $PxMgmtSrcAddrPrefixes installation variable).
  • Enabling support for dedicated hosting plans for Azure functions and VNet integration.

Note that you do not need to redeploy the Teams Connector if you need to change the Azure Network Security Group configuration, for example to add the IP address of a new Conferencing Node, update its certificate, or if you need to modify the number of Teams Connector instances.

Upgrading the Teams Connector to the latest software

When upgrading the Teams Connector to version 34, you must redeploy it using your original variables initialization script (although you may apply any configuration changes, if required), and with the latest application software files and v34 redeployment script, as described here.

Using CBA with version 34

Certificate-based authentication (CBA) is the default documented/scripted method from version 34 to authenticate the Teams Connector CVI application towards MS Graph. You can still use the previous password-based authentication method, but we plan to deprecate it in a future release, thus we recommend using CBA for new installations, or migrating to CBA as soon as practicable when upgrading existing deployments.

New upgrade steps for version 34

  • The default VM size for the Teams Connector has changed from Standard_F4s to Standard_D4s_v5, which is a more modern instance type.

    The supported instance types are now Standard_D4s_v5 (Intel), Standard_D4as_v5 (AMD), and Standard_F4s (old), and is now specified through a new $PxAzureVmSize variable and associated parameter in the installation/redeployment scripts.

    When selecting your instance type you should consider your VM quota, availability in the region you’re deploying to and pricing. The price and availability of Standard_D4s_v5 is very similar to Standard_F4s.

    You should review your VM quota and ensure that any requested increase is approved before performing the upgrade.

  • The upgrade steps described here assume that your existing deployment is using certificate-based authentication (CBA), and has been updated accordingly to use the PFX certificate for the Teams Connector CVI app.
  • Note that the standard upgrade steps (which apply to every release), as listed below, have been updated. They now require you to import (and install if you are first time user) specific required versions of Az Powershell and Microsoft.Graph Powershell modules.

Standard upgrade steps

  • If you (the person performing the upgrade) did not perform the initial installation, you should ensure that you have all the PowerShell modules with the supported versions installed.

    1. Open a new PowerShell ISE or PowerShell session before you install the modules.
    2. Run the following PowerShell commands (as Administrator):
    Copy to clipboard
    # Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

    Install-Module -Name Az.Accounts -RequiredVersion 2.13.2 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Automation -RequiredVersion 1.9.1 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Compute -RequiredVersion 7.1.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.EventHub -RequiredVersion 4.2.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.KeyVault -RequiredVersion 5.0.1 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Network -RequiredVersion 7.1.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Resources -RequiredVersion 6.12.1 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Storage -RequiredVersion 6.0.1 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Websites -RequiredVersion 3.1.2 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Microsoft.Graph.Authentication -RequiredVersion 2.11.1 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Microsoft.Graph.Applications -RequiredVersion 2.11.1 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Microsoft.Graph.Identity.DirectoryManagement -RequiredVersion 2.11.1 -Scope AllUsers -AllowClobber -Force

    Note that:

    • The Az PowerShell module collects telemetry data (usage data) by default, however you can opt out from this data collection using Disable-AzDataCollection (see this article for more information).
    • The Az PowerShell module remembers login information by default (i.e. you're not automatically logged out when closing your PowerShell window), but you can disable this with Disable-AzContextAutosave if required (see this article for more information).
  • You must import the required versions of PowerShell modules for this Teams Connector version:

    1. Open a new PowerShell ISE or PowerShell session.
    2. Change directory to the folder into which you extracted the files from the Teams Connector ZIP.
    3. Run the following PowerShell commands to import the required module versions:
    Copy to clipboard
    # Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

    # The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
    # By default, these files are blocked to protect the computer from untrusted files.
    Get-ChildItem -Recurse | Unblock-File

    # Import the PexTeamsCviApplication PowerShell module
    Import-Module .\PexTeamsCviApplication.psm1

    # Import Az Powershell modules
    Import-PexAzurePowershellModules -ErrorAction Stop
    # Import Microsoft.Graph Powershell modules
    Import-PexMicrosoftGraphPowershellModules -ErrorAction Stop
  • You must use the latest version of the redeploy script as contained here.

  • If you have deployed multiple Teams Connectors, you must follow the same redeploy process (with the appropriate variable initialization script) for each Teams Connector.
  • As with all upgrades, you can continue to use the Pexip CVI app from your existing deployment.
  • Your Pexip Infinity and Teams Connector installations must both be running the same software version (including minor/"dot" releases).

Redeploying the Teams Connector

The Teams Connector redeployment process described below is required when you want to:

  • Upgrade the Teams Connector software.
  • Change the Teams Connector's configuration (such as the names of the associated Conferencing Nodes).
  • Deploy a new Teams Connector in a different Azure region.

Note that there is no need to backup the Teams Connector as there are no specific settings, status or history information to preserve — if the deployment is lost you can just reinstall it with this redeploy process.

The redeployment process is summarized below:

  1. Check that you have the latest relevant version of the Teams Connector software, and your variable initialization and redeploy scripts.
  2. Delete the previous dynamic resource group and then recreate it for the new deployment, and ensure that the person performing the redeployment has the appropriate role for the resource groups in each region.
  3. Reinstall the Teams Connector software.

Before running your scripts we recommend that you check the Azure status (https://status.azure.com) for your region. Any ongoing issues in your region with the Azure services used by the Teams Connector could cause the script to fail.

The redeployment steps are shown in the following diagram and are then described in detail below.

Deployment script flowchart

Check Teams Connector software, retrieve your original scripts, and check your Azure environment

These instructions describe how to upgrade a Teams Connector that is already using CBA.

  1. Download the latest relevant version of the Teams Connector ZIP file (Pexip_Infinity_Connector_For_Microsoft_Teams_v34.1_<build>.zip) from the Pexip download page.

    Ensure that the Teams Connector version you download is the same version as your Pexip Infinity deployment (including minor/ "dot" releases).

  2. Extract the files to a folder on a local drive on your administrator PC.
  3. Add your PFX Teams Connector TLS certificate to this folder.
  4. Add your PFX certificate for the Teams Connector CVI app to this folder.
  5. Retrieve your saved copy of the initialization script. You should have created and stored your version of this script after you completed your initial installation of your first Teams Connector.
  6. Check your saved copy of the initialization script that sets the environmental variables:

    • If you are upgrading your Teams Connector, you should compare the saved copy of your initialization script against the current version of this script (as listed here), and adjust your script if necessary, for example if new variables have been added.
    • If you are redeploying and need to change any of the previous configuration you should also adjust your initialization script as required.
    • If you have Teams Connectors in many regions, ensure that you have the correct versions of the initialization scripts that set the regional variables to the appropriate values.
  7. Prepare your redeploy script:

    • If you are upgrading to v34, ensure that you use the latest version of the redeploy script and that you have updated it with your Pexip CVI App ID and CVI App certificate path, as described immediately below.
    • The CVI App ID and CVI App certificate password should have been stored in a password manager.

      Use the stored CVI App ID value to update the first of the two existing lines in the redeploy script that say:

      $AppId = ""

      $AppCertificatePath = ".\your_cvi_app_certificate.pfx"

      and set $AppCertificatePath to refer to the file name of the certificate that you retrieved in step 4.

      You'll be prompted for the CVI App certificate password later.

      This means that when you run the redeploy script, you will reuse the CVI app and CVI app certificate that you created the first time.

    • You should use the redeploy script in all scenarios except for when deploying a Teams Connector for the very first time for your Azure subscription i.e. you should use the redeploy script when upgrading, redeploying, or deploying a new Teams Connector in another region.
    • You only need one version of this script — you can use the same redeploy script in every region if you have multiple Teams Connectors.

Remove and then recreate the dynamic resource group and ensure appropriate roles are assigned to the resource groups

These steps must be performed by the Owner of the Azure subscription used for the Teams Connector.

  1. Run the following PowerShell command to connect to Azure:

    • In all standard deployments run:

      Connect-AzAccount

    • If this is a GCC High / Azure US Government Cloud deployment then use this command instead:

      Connect-AzAccount -EnvironmentName AzureUSGovernment

    Then follow the prompts to sign in to Azure.

  2. Run the variable initialization script that you used when your first installed the Teams Connector (to set the required subscription, resource group name and region variables).
  3. Ensure that you are using the Azure subscription for the Teams Connector:

    Set-AzContext -SubscriptionId $PxSubscriptionId

  4. Run the following script. It first deletes the existing dynamic resource group and then recreates it for the new/redeployed Teams Connector.

    Copy to clipboard
    # Remove the existing dynamic resource groups
    $PxTeamsConnResourceGroup = Get-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -ErrorAction SilentlyContinue
    if ($PxTeamsConnResourceGroup) {
    # Disassociate NSG from the VMSS subnet
    $nsg = Get-AzNetworkSecurityGroup -ResourceGroupName $PxTeamsConnResourceGroupName -ErrorAction SilentlyContinue
    if ($null -ne $nsg) {
    $vmssSubnet = $nsg.Subnets | Where-Object { $_.Id.EndsWith("vmss-subnet") }
    if ($null -eq $vmssSubnet) {
    Write-Warning "NSG is not attached to the VMSS subnet"
    } else {
    $subnetConfig = Get-AzVirtualNetworkSubnetConfig -ResourceId $vmssSubnet.Id
    $existingVnet = Get-AzVirtualNetwork -Name $vmssSubnet.Id.Split('/')[8] -ResourceGroupName $vmssSubnet.Id.Split('/')[4]
    Set-AzVirtualNetworkSubnetConfig -Name $vmssSubnet.Id.Split("/")[-1] -AddressPrefix $subnetConfig.AddressPrefix -VirtualNetwork $existingVnet -NetworkSecurityGroupId $null -ServiceEndpoint @("Microsoft.Storage", "Microsoft.KeyVault", "Microsoft.EventHub") | Out-Null
    Write-Warning "The next command will disassociate subnet $($vmssSubnet.Id.Split("/")[-1]) from NSG $($nsg.Name)"
    $confirmation = "Y"
    $confirmation = Read-Host -Prompt 'Do you wish to proceed? [Y] Yes [N] No (default is "Y")'
    if ($confirmation -eq "Y") {
    $existingVnet | Set-AzVirtualNetwork | Out-Null
    }
    }
    }
    $resources = Get-AzResource -ResourceGroupName $PxTeamsConnResourceGroupName
    $resNames = $resources | ForEach-Object { return "`n" + $_.Name + " " + $_.ResourceType }
    Write-Host "In order to redeploy Pexip Teams Connector, resource group $PxTeamsConnResourceGroupName has to be deleted. Resources: $resNames"
    Remove-AzResourceGroup -Name $PxTeamsConnResourceGroupName | Out-Null
    }
    $PxTeamsConnResourceGroup = Get-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -ErrorAction SilentlyContinue
    if ($null -ne $PxTeamsConnResourceGroup) {
    Write-Warning "$PxTeamsConnResourceGroupName still exists, however it has to be removed before redeploying!"
    } else {
    # Create resource group for Teams Connector VMSS (per region)
    # This is region specific; ensure that the initial variables are set with the
    # correct values for $PxAzureLocation, $PxTeamsConnFqdn and $PxVmssRegion
    New-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -Tag $tags
    }
  5. Ensure that the person performing the redeploy/upgrade has the Azure Owner role for the static and dynamic resource groups, and Contributor role for the Azure Bot resource group. If you have deployed in multiple regions you must do this for all of the resource groups in each region.

    If the Owner of the Azure subscription will be performing the redeploy/upgrade then this step can be skipped, otherwise the subscription Owner must assign the required roles to the person performing the upgrade. You do this by running the following commands:

    New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Owner" -ResourceGroupName $PxTeamsConnStaticResourceGroupName

    New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Owner" -ResourceGroupName $PxTeamsConnResourceGroupName

    New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Contributor" -ResourceGroupName $PxBotResourceGroupName

    where <email_name> is the email address / user principal name of the person who will perform the remaining upgrade/redeploy steps; for example where alice@example.com will perform the upgrade/redeploy, the SignInName would be -SignInName alice@example.com for the commands listed above.

Note:

  • In the future, if another person were to upgrade or redeploy the Teams Connector, that person would also have to be granted the appropriate roles for these resource groups.
  • You can also use the Azure portal to check/assign permissions by selecting the resource group and using the Access control (IAM) option.

Redeploy the Teams Connector

To redeploy the Teams Connector:

  1. Ensure that you have Owner permissions for the API app (check App registrations in the Azure portal); see Assigning Owner permissions for the API app if you do not have permission.
  2. In PowerShell, run your initialization script that sets the environmental variables.

    If you have Teams Connectors in many regions, ensure that you run the version of the initialization script that sets the regional variables to the appropriate values.

  3. In PowerShell run your redeploy script.

    You only need one version of this script — you can use the same script in every region if you have multiple Teams Connectors.

This is the redeploy script. It is a variation on the installation script that only performs the necessary commands to redeploy the Teams Connector. As with the initial installation, we recommend running each group of commands step-by-step within PowerShell.

This script applies to software version 34. If you are using an earlier version you should refer to our previous documentation.

  • Standard deployment
  • GCC High / Azure US Government Cloud deployment
Copy to clipboard
# Ensure the correct script and software combination is being used
try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

if ($PxConnMajorVersion -ne "34"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 34"}

# Connect to PowerShell Azure Resource Manager account
# Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

# The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
# By default, these files are blocked to protect the computer from untrusted files.
Get-ChildItem -Recurse | Unblock-File

# Connect to Azure with an authenticated account for use with Azure Resource Manager (in same window to reuse variables)
Connect-AzAccount

# Import the PexTeamsCviApplication PowerShell module
Import-Module .\PexTeamsCviApplication.psm1

# Connect to Graph
Connect-PexTeamsMsGraph

# Before running the following commands, update the following 2 lines/variables with the CVI App ID and
# the path to the CVI App certificate file that were output when the original installation script was run
# You'll be prompted for the CVI App certificate password later.
$AppId = ""
$AppCertificatePath = ".\your_cvi_app_certificate.pfx"

# Change context to the Pexip Subscription
Set-AzContext -SubscriptionId $PxSubscriptionId

# Virtual Machine Scale Set (VMSS) creation
# Provide credentials to be used as local user/password for Pexip Teams Connector VMs
# Create a password (using the initialization script variables) for the Windows VM
$PxWinAdminSecurePassword = ConvertTo-SecureString -AsPlainText $PxWinAdminPassword -Force
$PxWinAdminCred = New-Object System.Management.Automation.PSCredential -ArgumentList $PxWinAdminUser,$PxWinAdminSecurePassword

# Optionally if you did not want to specify the password as a variable, use Get-Credential
# $PxWinAdminCred = Get-Credential

# Deploy the Teams Connector VMs
# this step can take up to 30 minutes to complete
.\create_vmss_deployment.ps1 -SubscriptionId $PxSubscriptionId -AzureVmSize $PxAzureVmSize -ResourceGroupName $PxTeamsConnResourceGroupName -VmssName "$($PxBaseConnName)$($PxVmssRegion)" -VMAdminCredential $PxWinAdminCred -PfxPath $PxPfxCertFileName -TeamsConnectorFqdn $PxTeamsConnFqdn -PexipFqdns $PxNodeFqdns -instanceCount $PxTeamsConnInstanceCount -AppId $AppId -AppCertificatePath $AppCertificatePath -StaticResourcesResourceGroupName $PxTeamsConnStaticResourceGroupName -IncidentReporting $PxTeamsConnIncidentReporting -RdpSourceAddressPrefixes $PxMgmtSrcAddrPrefixes -PexipSourceAddressPrefixes $PxNodesSourceAddressPrefixes -WupdScheduledInstallDay $PxWupdScheduledInstallDay -WupdScheduledInstallTime $PxWupdScheduledInstallTime -WupdActiveHoursStart $PxWupdActiveHoursStart -WupdActiveHoursEnd $PxWupdActiveHoursEnd -CustomerUsageAttribution $PxCustomerUsageAttribution -UseAzureHybridBenefit $PxUseAzureHybridBenefit -Tag $tags -TeamsConnectorApiApplicationId $TeamsConnectorApiApplicationId -FunctionsDedicatedHostingPlan $FunctionsDedicatedHostingPlan -EventHubSourceAddressPrefixes $EventHubSourceAddressPrefixes -VnetIntegration $VnetIntegration -PexipConfiguredConnectorFqdn $PexipConfiguredConnectorFqdn -PexipOutboundFqdn $PexipOutboundFqdn -ExistingVNETResourceId $PxExistingVNETResourceId -UsePrivateRouting $PxUsePrivateRouting

# supply the PFX certificate file password when prompted

# Please enter the password for the PFX certificate '.\xxxxxxxx.pfx': ***************

# supply the PFX CVI app certificate file password when prompted

# Please enter the password for the CVI app PFX certificate '.\xxxxxxxx.pfx': ***************

# Printing finished message
Write-Host
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host " All steps completed."
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host
Copy to clipboard
# This script only applies to GCC High / Azure US Government Cloud deployments

# Ensure the correct script and software combination is being used
try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

if ($PxConnMajorVersion -ne "34"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 34"}

# Set VmImage variable to hold the CIS STIG image properties - STIG image is optional but typical
# In a later step in this script you can choose not to use the STIG image 
$VmImage = @{
"sku"  = "cis-windows-server2019-stig-gen1"
"offer"  = "cis-windows-server"
"publisher" = "center-for-internet-security-inc"
"version"  = "latest"}

# Connect to PowerShell Azure Resource Manager account
# Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

# The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
# By default, these files are blocked to protect the computer from untrusted files.
Get-ChildItem -Recurse | Unblock-File

# Connect to Azure USGovernment with an authenticated account for use with Azure Resource Manager (in same window to reuse variables)
Connect-AzAccount -EnvironmentName AzureUSGovernment

# Import the PexTeamsCviApplication PowerShell module
Import-Module .\PexTeamsCviApplication.psm1

# Connect to Graph
Connect-PexTeamsMsGraph

# Before running the following commands, update the following 2 lines/variables with the CVI App ID and
# the path to the CVI App certificate file that were output when the original installation script was run
# You'll be prompted for the CVI App certificate password later.
$AppId = ""
$AppCertificatePath = ".\your_cvi_app_certificate.pfx"

# Change context to the Pexip Subscription
Set-AzContext -SubscriptionId $PxSubscriptionId

# Virtual Machine Scale Set (VMSS) creation
# Provide credentials to be used as local user/password for Pexip Teams Connector VMs
# Create a password (using the initialization script variables) for the Windows VM
$PxWinAdminSecurePassword = ConvertTo-SecureString -AsPlainText $PxWinAdminPassword -Force
$PxWinAdminCred = New-Object System.Management.Automation.PSCredential -ArgumentList $PxWinAdminUser,$PxWinAdminSecurePassword

# Optionally if you did not want to specify the password as a variable, use Get-Credential
# $PxWinAdminCred = Get-Credential

# Deploy the Teams Connector VMs
# this step can take up to 30 minutes to complete
# if you are not using a STIG image then remove the following parameter from this command: -VmImage $VmImage
.\create_vmss_deployment.ps1 -SubscriptionId $PxSubscriptionId -AzureVmSize $PxAzureVmSize -ResourceGroupName $PxTeamsConnResourceGroupName -VmssName "$($PxBaseConnName)$($PxVmssRegion)" -VMAdminCredential $PxWinAdminCred -PfxPath $PxPfxCertFileName -TeamsConnectorFqdn $PxTeamsConnFqdn -PexipFqdns $PxNodeFqdns -instanceCount $PxTeamsConnInstanceCount -AppId $AppId -AppCertificatePath $AppCertificatePath -StaticResourcesResourceGroupName $PxTeamsConnStaticResourceGroupName -IncidentReporting $PxTeamsConnIncidentReporting -RdpSourceAddressPrefixes $PxMgmtSrcAddrPrefixes -PexipSourceAddressPrefixes $PxNodesSourceAddressPrefixes -WupdScheduledInstallDay $PxWupdScheduledInstallDay -WupdScheduledInstallTime $PxWupdScheduledInstallTime -WupdActiveHoursStart $PxWupdActiveHoursStart -WupdActiveHoursEnd $PxWupdActiveHoursEnd -CustomerUsageAttribution $PxCustomerUsageAttribution -UseAzureHybridBenefit $PxUseAzureHybridBenefit -Tag $tags -TeamsConnectorApiApplicationId $TeamsConnectorApiApplicationId -FunctionsDedicatedHostingPlan $FunctionsDedicatedHostingPlan -EventHubSourceAddressPrefixes $EventHubSourceAddressPrefixes -VnetIntegration $VnetIntegration -VmImage $VmImage -TeamsEnvironmentName TeamsGCCHigh -PexipConfiguredConnectorFqdn $PexipConfiguredConnectorFqdn -PexipOutboundFqdn $PexipOutboundFqdn -ExistingVNETResourceId $PxExistingVNETResourceId -UsePrivateRouting $PxUsePrivateRouting

# supply the PFX certificate file password when prompted

# Please enter the password for the PFX certificate '.\xxxxxxxx.pfx': ***************

# supply the PFX CVI app certificate file password when prompted

# Please enter the password for the CVI app PFX certificate '.\xxxxxxxx.pfx': ***************

# Printing finished message
Write-Host
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host " All steps completed."
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host

Migrating (upgrading) an existing Teams Connector using password-authentication to CBA

If you already have a Teams Connector deployed with password-based authentication, you can switch to a certificate-based authentication model.

Note that the instructions below generate and use a self-signed certificate; see Using your own certificate for the CVI App if you want to use your own certificate instead.

To switch to certificate-based authentication:

  1. Ensure that you are an owner of the Pexip CVI Application.
  2. Download the latest relevant version of the Teams Connector ZIP file (Pexip_Infinity_Connector_For_Microsoft_Teams_v34.1_<build>.zip) from the Pexip download page.
  3. Extract the files to a folder on a local drive on your administrator PC.
  4. Start a PowerShell session as Administrator.
  5. After launching PowerShell you must change directory to the folder into which you extracted the files from the Teams Connector ZIP.
  6. Assign the $AppId variable with your CVI App ID (as contained within your existing redeploy script).
  7. Run the following commands:

    Copy to clipboard
    # Ensure the correct script and software combination is being used
    try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

    if ($PxConnMajorVersion -ne "34"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 34"}
    Connect-AzAccount

    # Import the PexTeamsCviApplication PowerShell module
    Import-Module .\PexTeamsCviApplication.psm1

    # Connect to Graph
    Connect-PexTeamsMsGraph

    $AppCertificatePath = New-PexTeamsCviApplicationCertificateCredential -AppId $AppId -ValidityInMonths 24
    $AppCertificatePath = $AppCertificatePath.Trim()
    # Please enter the password for the CVI app PFX certificate: ********************
    # Verifying - Enter the password for the CVI app PFX certificate: ********************
    # Your PFX certificate including the private key has been stored at '{absolute path}'
    # The certificate is valid from '{notBefore}' to '{notAfter}' (UTC)
    # CVI application certificate credential 'pexip-cvi-app-certificate-[{date}]' has been successfully uploaded to Microsoft Entra ID

    Enter the password for the CVI app PFX certificate when prompted. We recommend that you create and save the CVI App PFX certificate password using a password manager.

    Regarding the CVI App certificate, you should note that:

    • The script passes a -ValidityInMonths parameter to the PexTeamsCviApplicationCertificateCredential cmdlet to specify the validity period of the CVI App certificate. In this case it specifies "-ValidityInMonths 24" i.e. 2 years but you can specify your own period as required.
    • The Teams Connector application will stop working if the CVI App certificate expires. We recommend that you set certificate contact notifications (see this Microsoft article) as they can warn you of certificates that are due to expire.
  8. Store the CVI App certificate PFX file in a safe location.
  9. Now you can follow the redeploy instructions above.

Using your own certificate for the CVI App

The procedure above generates and uses a self-signed certificate. If you want to use your own certificate instead:

  • The certificate must be a .pfx certificate.
  • The CVI App certificate must be different from the Teams Connector certificate.
  • You have to manually upload its public key (.cer/.pem/.crt) to the CVI application via the Microsoft Entra admin center — see this article for instructions.
  • You have to specify its location in the $AppCertificatePath variable when preparing your installation/redeploy script.

    Replace this line

    $AppCertificatePath = New-PexTeamsCviApplicationCertificateCredential -AppId $AppId -ValidityInMonths 24

    with

    $AppCertificatePath = "C:\your_cvi_app_certificate.pfx"

Updating the Teams Connector TLS certificate or the CVI app certificate

The Teams Connector TLS certificate and the CVI app certificate (when using CBA to authenticate the Teams Connector CVI application towards MS Graph) are stored in the Azure key vault and can be updated without having to redeploy the Teams Connector. The old (existing) certificates can be updated when they are expiring or when they have already expired. We recommend updating the certificates before they expire to avoid service disruptions.

If you need to roll back to an older (but still valid) version of a certificate, you must follow these steps to import it as an additional certificate. Simply disabling the current certificate will not automatically revert to the previous version.

See Teams Connector certificate requirements for more information about the certificate requirements.

Note:

  • An alarm is raised on Pexip Infinity when the Teams Connector TLS certificate is due to expire within the next 30 days, and if it has expired. Currently there are no alarms raised if the CVI app certificate is due to expire.
  • You can use the test_pfx_certificate.ps1 script (which is in the Teams Connector ZIP file) to verify the currently installed Teams Connector TLS certificate (you cannot use it on the CVI app certificate). The command takes the format (run your variables initialization script first):

    test_pfx_certificate.ps1 -TeamsConnectorFqdn $PxTeamsConnFqdn -PfxPath $PxPfxCertFileName -PfxPassword <certificate password>

  • If you need to create a new CVI app certificate, follow steps 1-7 of the instructions at Migrating (upgrading) an existing Teams Connector using password-authentication to CBA.

To update either the Teams Connector TLS certificate or the CVI app certificate:

  1. In the Azure portal, for your subscription, select the Teams Connector static resource group (which typically has a name in the style <prefix>-TeamsConn-<region>-static-RG).
  2. Ensure that you are an owner of the resource group.
  3. Select the Key vault in that resource group.
  4. Add a Key Vault Certificates Officer role (a4417e6f-fecd-4de8-b567-7b0420556985) for your user principal (see this article for instructions).
  5. Open the Certificates pane (under Settings).

    (Note that the screenshot examples below are for the Teams Connector TLS certificate.)

    If you have VNet integration enabled and you see a warning "Firewall is turned on and your client IP address is not authorized to access this key vault" then you need to temporarily add your client IP address in the key vault’s Networking settings (Firewall > + Add your client IP address).

  6. Select the relevant certificate:

    • To update the Teams Connector TLS certificate: select the certificate named pexip-teams-connector-certificate.
    • To update the CVI app certificate: select the certificate named pexip-cvi-app-certificate.

    (Don't create/import a new certificate under a different name.)

  7. Select New Version.

  8. Select Import as the creation method.

  9. Select your new pfx certificate and provide a password if the certificate is password protected.
  10. Import the certificate.

    After importing a certificate any alarm in Pexip Infinity related to an expiring or expired Teams Connector TLS certificate will be lowered, but the new certificate is not applied across the VMSS yet.

    There is no need to delete the expired certificate.

  11. You have to reboot the scale set to apply the new certificate version.

    To do this, in the Azure portal, for your subscription, select the Teams Connector dynamic resource group (which typically has a name in the style <prefix>-TeamsConn-<version>-<region>-RG where <version> is optional), then the Virtual Machine Scale Set and select the Restart option from the top menu.

    Perform the reboot during out-of-hours — rebooting the scale set drops any existing calls.

  12. After a few minutes, when the instances have restarted, verify that you can make calls and that the desired state configuration (from within your dynamic resource group, select the Automation Account, and then State configuration DSC) is green for all the running VMSS instances. (Some instances might be deallocated if using scheduled scaling — these instances will be provisioned with the new certificate on startup.)

We recommend that you set certificate contact notifications (see this Microsoft article) as they can warn you of certificates that are due to expire.

Assigning Owner permissions for the API app

The person who will be performing the deployment must have Owner permissions for the API app.

When necessary, the script below can be used by the current Owner to assign the Owner permission to another user.

Note that you must have run the variables script to assign the $TeamsConnectorApiApplicationId variable and you must replace <email_name> in the script with the email address / user principal name of the person who will perform the remaining installation steps.

  1. Run the following PowerShell command to connect to Azure:

    • In all standard deployments run:

      Connect-AzAccount

    • If this is a GCC High / Azure US Government Cloud deployment then use this command instead:

      Connect-AzAccount -EnvironmentName AzureUSGovernment

    Then follow the prompts to sign in to Azure.

  2. Run the variables script to assign the $TeamsConnectorApiApplicationId variable.
  3. Copy the script below:

    1. You must replace <email_name> in the script with the email address / user principal name of the person who will perform the remaining installation steps.

      For external users (guests in a tenant) the -UserId parameter should be in the form "<emailname_domain>#EXT#@<tenant_url>". For example, for external users, if the external user has an email name of guestname@guestdomain.com and is a guest in maintenant.com, then you would specify (note the _ replacing the @ between guestname and guestdomain.com):

      -UserId "guestname_guestdomain.com#EXT#@maintenant.onmicrosoft.com"

    2. Run the script.
    Copy to clipboard
    # Import the PexTeamsCviApplication PowerShell module
    Import-Module .\PexTeamsCviApplication.psm1

    # Connect to Graph
    Connect-PexTeamsMsGraph

    # Import the HelperFunctions PowerShell module
    Import-Module .\HelperFunctions.psm1

    # Get Graph url for this environment
    $graphUrl = GetMsGraphUrlForAzureEnvironment

    # Get the API application registration reference
    $apiApp = Get-MgApplication -Filter "AppId eq '${TeamsConnectorApiApplicationId}'"

    # Make sure you have Microsoft.Graph.Users Powershell module installed
    Install-Module -Name Microsoft.Graph.Users -RequiredVersion 2.11.1 -Scope AllUsers -AllowClobber -Force
    Import-Module Microsoft.Graph.Users -RequiredVersion 2.11.1

    # Get the assignee
    # Replace <email_name> with the email address / user principal name of the person to perform the remaining installation steps
    $user = Get-MgUser -UserId <email_name>

    # Assign owner role for the API application registration to the assignee
    $newOwner = @{
    "@odata.id"= "$($graphUrl)v1.0/directoryObjects/$($user.Id)"
    }
     
    New-MgApplicationOwnerByRef -ApplicationId $apiApp.Id -BodyParameter $newOwner

    # Get the service principal associated with the API application
    $apiAppSp = Get-MgServicePrincipal -Filter "AppId eq '${TeamsConnectorApiApplicationId}'"

    # Assign owner role for the API application service principal to the assignee
    New-MgServicePrincipalOwnerByRef -ServicePrincipalId $apiAppSp.Id -BodyParameter $newOwner

Maintaining access to the Admin Consent web page

Reinstating the Admin Consent web page

If you are upgrading and you need to maintain access to the Admin Consent web page (typically only necessary if you are a service provider), then after completing the commands in the redeploy script you should also run the following additional PowerShell commands to reinstate the Admin Consent web page:

Import-Module .\PexTeamsCviApplication.psm1

$AdminConsentUrl = Publish-PexTeamsAdminConsentWebSite -SubscriptionId $PxSubscriptionId -ResourceGroupName $PxBotResourceGroupName -PxBaseConnName $PxBaseConnName -AppId $AppId -SourceAddressPrefixes $PxConsentSourceAddressPrefixes -Confirm:$false -Tag $tags

and then

Write-Host "To give consent to the CVI app, go to: $AdminConsentUrl"

Note that if you run the above commands in a new window/session you will first need to run the PowerShell variables initialization script.

Changing the workstation / management network addresses that can access the consent page

To change the workstation / management network addresses that can provide consent for the Teams Connector CVI app (the addresses that were initially specified in $PxConsentSourceAddressPrefixes):

  1. In the Azure portal, go to the Azure bot resource group — this is called <prefix>-TeamsBot-RG.
  2. Select the App Service object.
  3. Under Settings, select Networking.
  4. Select Configure Access Restrictions.
  5. Modify the addresses as required and save your changes.

Adding or removing Conferencing Nodes

You can change the pool of Conferencing Nodes that communicates with the Teams Connector without having to redeploy the Teams Connector itself, providing that the certificate installed on any new Conferencing Nodes contains an identity that was in the $PxNodeFqdns initialization script variable when the Teams Connector was originally deployed.

For example, if you have a Teams Connector deployed as shown in Certificate and DNS examples for a Microsoft Teams integration i.e.

  • two existing Conferencing Nodes called px01.vc.example.com and px02.vc.example.com
  • both nodes have the same certificate installed with subject name px.vc.example.com, and altNames px.vc.example.com, px01.vc.example.com and px02.vc.example.com
  • the Teams Connector was deployed with the $PxNodeFqdns variable set to px.vc.example.com

and you want to add a new Conferencing Node px03.vc.example.com, you would have to:

  1. Install a certificate on the new Conferencing Node that contains the common px.vc.example.com identity.

    To remain consistent with our example certificate naming policy this would mean creating a new certificate with a subject name of px.vc.example.com and altNames of px.vc.example.com, px01.vc.example.com, px02.vc.example.com and px03.vc.example.com. You would then install this certificate on the new node and the two existing nodes.

    Note that purely from a Teams Connector perspective, the node certificate only needs to contain the identity specified in the $PxNodeFqdns variable, but if the same Conferencing Nodes handle SIP and Skype for Business signaling then the example certificate naming policy used here is more appropriate.

  2. You may need to update the Network Security Group associated with your Teams Connector in Azure.

    The "MCU-signalling-endpoint" rule (priority 110) specifies the IP addresses of the Conferencing Nodes that can communicate with the Teams Connector. These addresses were based on the value of the $PxNodesSourceAddressPrefixes initialization script variable. If individual IP addresses were specified then you need to add the IP address of the new Conferencing Node to this NSG rule. If the variable specified an IP subnet and the new node's address is within that subnet, then no changes are required.

  3. If you had to update the NSG rule, you should add the same new address to the $PxNodesSourceAddressPrefixes variable in your stored initialization script to keep it in sync with your actual deployment in case it is needed for a future redeployment or upgrade.

Removing Conferencing Nodes

If you need to remove a Conferencing Node from the pool for any reason, you do not need to make any immediate changes to your Teams Connector / Azure configuration. However, you should make any necessary changes to the $PxNodesSourceAddressPrefixes variable in your stored initialization script to keep it in sync with your actual deployment.

Changing the alternative dialing instructions or IVR address

You can use the Set-CsVideoInteropServiceProvider command to change the alternative dialing instructions or the IVR address (TenantKey).

Changing the alternative dialing instructions

You can update the webpage of "Alternate VTC dialing instructions" that the recipient of the meeting invite can look at, by adding or removing some of the address types that are displayed.

You do this by using the Set-CsVideoInteropServiceProvider command and supplying a new InstructionUri parameter, following the same rules as described when you first created the service provider.

In our original example, the service provider was created with the command:

New-CsVideoInteropServiceProvider -Name Pexip -TenantKey "teams@example.com" -InstructionUri "https://px.vc.example.com/teams/?conf={ConfId}&ivr=teams&d=example.com&ip=198.51.100.40&test=test_call&w&qrcode" -AllowAppGuestJoinsAsAuthenticated $true -AadApplicationIds "c054d1cb-7961-48e1-b004-389e81356232"

To change the instructions to remove the "Test call" option, for example, the revised InstructionUri parameter would be "https://px.vc.example.com/teams/?conf={ConfId}&ivr=teams&d=example.com&ip=198.51.100.40&w&qrcode"

and the command to apply the revised InstructionUri parameter would be:

Set-CsVideoInteropServiceProvider -Identity Pexip -InstructionUri "https://px.vc.example.com/teams/?conf={ConfId}&ivr=teams&d=example.com&ip=198.51.100.40&w&qrcode"

Changing the IVR address (TenantKey)

The IVR address (TenantKey) is the alias that you assign to the Pexip Virtual Reception that is to act as the IVR gateway into the Teams meetings. In our original example this was set to teams@example.com.

To change the address you can use the Set-CsVideoInteropServiceProvider command and supply a new TenantKey parameter, for example:

set-CsVideoInteropServiceProvider -Identity Pexip -TenantKey "newaddress@example.com"

Note that when using Set-CsVideoInteropServiceProvider, the first parameter is called -Identity, not -Name.

These changes may take up to 6 hours to come into effect.

Changing the call capacity of a Teams Connector

When you install a Teams Connector CVI application in Azure, you initially specify the number of Teams Connector instances (VMs) to deploy.

You can subsequently modify the number of instances via the Azure portal, to reflect changing capacity requirements, or if you have enabled the Azure Event Hub you can also automate/schedule changes in call capacity to suit your requirements.

See Scheduling scaling and managing Teams Connector capacity for full details.

Changing management workstation access

When you deploy a Teams Connector, a Network Security Group (NSG) is created within Azure. The NSG includes an "RDP" rule (priority 1000) that controls RDP access to the Teams Connector instances from any addresses specified in the $PxMgmtSrcAddrPrefixes installation variable.

If no addresses were specified then a Deny rule is created instead. If you want to subsequently allow RDP access you must do a full redeploy. You cannot just convert the Deny rule into an Allow rule (as other associated Teams Connector settings also have to be modified).

You can change this rule if you want to specify a different set of management workstation addresses. To do this:

  1. In the Azure portal, for your subscription, go to the Network security group in your Teams Connector resource group.
  2. Select rule 1000 RDP.
  3. Change the Source IP addresses/CIDR ranges as appropriate for the management workstation / network subnet addresses you want to allow RDP access.
  4. Select Save.
  5. Update the $PxMgmtSrcAddrPrefixes installation variable in your stored initialization script to match your changes applied to the NSG to keep the script in sync with your actual deployment.

Mandating the use of Availability Zones

By default the Teams Connector uses Azure Availability Zones if they are available in the selected region. However if you want to mandate the use of Availability Zones you can add an extra parameter to the call to create_vmss_deployment.ps1 in your installation/redeployment script.

The parameter is -UseAvailabilityZones and can be set to either "BestEffort" (the default) or "Mandatory".

If you use "Mandatory" and Availability Zones are not available in the selected region then the deployment will fail with an error: "Availability zones not available for the selected region or the VM type is not available in the availability zones". See Azure regions with Availability Zones for the list of supported regions.

Monitoring the Teams Connector

This section contains optional configuration in Azure for administrators who want to collect metrics and Windows event logs into Azure log analytics workspace and Azure Monitor Metrics (in preview at the time of writing).

  1. From within the Azure portal, go to the Teams Connector's dynamic resource group and select + Create.
  2. Use the search bar to find and select Log Analytics Workspace.
  3. Select Create to add the Log Analytics Workspace in your dynamic resource group.

    1. Your subscription and resource group should be preselected.
    2. Enter a Name, for example "pexip-teams-connector-log-analytics".
    3. Select a Region.
    4. Select Review + Create.

    5. Select Create (after the validation stage completes).
  4. Wait for the workspace deployment to complete and select Go to resource.
  5. Go to Agents management and select Data Collection Rules.
  6. Select + Create to create a Data Collection Rule.

    1. On the Basics tab:

      1. Enter a Name, for example "pexip-teams-connector-dcr", and select a Region.
      2. Leave the Platform Type as Windows.
    2. On the Resources tab:

      1. Select + Add resources.
      2. Use the search bar to find, select and Apply the Virtual machine scale set for your Teams Connector.
    3. On the Collect and deliver tab.

      1. Select + Add data source.
      2. Choose a Data source type of Performance counters.
      3. Select the required performance counters.
      4. As a Destination, select Azure Monitor Logs and choose your log analytics workspace. You can also send these metrics to Azure Monitor Metrics (in preview at the time of writing).
      5. Select Add data source.
      6. Add a second data source: repeat the above steps for a data source of Windows event logs.
      7. Select Review + Create, and then select Create.

  7. This installs extension AzureMonitorWindowsAgent onto your VMSS instances. The agent will start sending metrics and logs to your log analytics workspace, although this can take some time.

Reviewing your log analytics workspace status and metrics

From within your log analytics workspace resource, you can go to Monitoring > Insights (or Settings > Agents management) to check whether the agents are connected to your workspace.

In the Log analytics workspace you can query the event logs or performance metrics in the General > Logs pane.

In Azure Monitor > Metrics you can view the metrics/logs of the VMSS by selecting the correct scope pointing to the resource itself. In Metrics you can either choose "guest" or "host" metrics.

The above is only an example of monitoring configuration. If you want to persist the log analytics workspace, you could deploy it in the static resource group and only recreate the data collection rules after each Teams Connector redeployment. Monitoring can also be set up against an already existing log analytics workspace. You can also collect custom performance counters and custom event logs.

Enabling diagnostic logs

Most of the Azure resources support sending of diagnostic logs to a specified destination. To enable some of these to output logs to log analytics workspace, see the following settings.

Key Vault

Event Hub

VMSS

  1. Go to VMSS resource > properties and copy resource ID.
  2. Go to Log analytics workspace resource > properties and copy resource ID.
  3. Decide on your data retention (specified in days).
  4. Enable diagnostic settings using PowerShell. Make sure you connect to the correct tenant and subscription beforehand.
Copy to clipboard
$resourceId = {previously retrieved resource id}
$workspaceId = {previously retrieved workspace id}
# Modify retention in days based on your requirements
$retentionDays = 30
Set-AzDiagnosticSetting -ResourceId $resourceId -Enabled $True -WorkspaceId $workspaceId -RetentionEnabled $True -RetentionInDays $retentionDays -EnableLog $true -EnableMetrics $true

Data retention for the whole log analytics workspace

See this article for information about configuring the default workspace retention policy.

Uninstalling the Teams Connector

This section describes how to completely remove a Teams Connector installation, for example if you have a test system that you no longer need.

  1. Delete all of the resource groups from Azure:

    1. Identify all of your existing Teams Connector resources in Azure: in the Azure portal, for your subscription, go to Resource groups and search for the prefix that you used when naming your resources — this is the value of the $PxBaseConnName variable in the initialization script.

      You will see resource groups with names in the following formats:

      • <prefix>-TeamsBot-RG: this contains the Azure Bot.
      • <prefix>-TeamsConn-<region>-RG: this contains the Teams Connector instances (Virtual Machine scale set).
      • <prefix>-TeamsConn-<region>-static-RG: this includes the Azure Key Vault and the public IP address of the Teams Connector.

      If you have deployed a Teams Connector in multiple regions you will see several <prefix>-TeamsConn-... resource groups.

    2. Select each resource group in turn (with the prefix of the Teams Connector you want to delete), and then select Delete resource group and confirm with the name of the resource group.

      Note that the Azure Key Vault is only soft-deleted when the static resource group is deleted. This means that if you subsequently redeploy your Teams Connector using the same variables initialization script, you will encounter deployment errors due to conflicts with key vault object names. To avoid this you must first purge the soft-deleted key vault:

      1. Go to the Key Vaults services within Azure.
      2. Select Manage deleted vaults.
      3. Select the subscription and purge the key vault.

  2. Remove the App registrations from Azure:

    1. Within the Azure portal, select Azure Active Directory.
    2. Under Manage, select App registrations.
    3. Select the two app registrations (the CVI app and the API app) with the prefix of the Teams Connector you want to delete, and then Delete them.
  3. Remove the Cloud Video Interop service provider from your tenant:

    1. Start a PowerShell session and run the following commands to sign in to your Teams tenant:

      • In all standard deployments run:

        Import-Module MicrosoftTeams

        Connect-MicrosoftTeams

      • If this is a GCC High / Azure US Government Cloud deployment then use these commands instead:

        Import-Module MicrosoftTeams

        Connect-MicrosoftTeams -TeamsEnvironmentName TeamsGCCH

    2. Run the command:

      Remove-CsVideoInteropServiceProvider -Identity Pexip

      To run the command, you need the Global administrator role.

  4. Remove references to the Teams Connector from the Pexip Management Node:

    1. Change or delete any locations, Virtual Receptions or Call Routing Rules that are using the Teams Connector.
    2. Go to Call control > Microsoft Teams Connectors and delete the Teams Connector address.
  5. Remove from DNS the record that refers to the FQDN of the Teams Connector load balancer.