Using certificate-based authentication for the Teams Connector CVI application

From version 33 you can use certificate-based authentication (CBA) to authenticate the Teams Connector CVI application towards MS Graph. In version 33, CBA is optional and the previous password-based authentication method is still the default mechanism.

The CBA method will be the default and recommended mechanism in version 34. Password-based authentication will still be supported in version 34 but we plan to deprecate it in a future release, thus we recommend migrating to CBA as soon as practicable.

This topic explains how to use CBA instead of password-based authentication with version 33 of the Teams Connector. It covers:

Deploying a new (first time) Teams Connector with certificate-based authentication

You can follow most of the standard steps for installing the Teams Connector. However, there are some variations to the installation script and the post-deploy process as described below.

Remember to run your standard variable initialization script first (the variable script is the same for either authentication method), before running this installation script.

The installation script for certificate-based authentication is provided below.

Note that:

  • The script passes a -ValidityInMonths parameter to the PexTeamsCviApplicationCertificateCredential cmdlet to specify the validity period of the 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.
  • 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 "33"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 33"}

# Connect to Microsoft Graph, Azure Resource Manager account and import Pexip CVI module
# Microsoft Graph commands
# Connect to Microsoft Graph
# If AAD/365 admin account is not the same as Azure Resource Manager admin account,
# the next section is to be run by the AAD admin.
#
# IMPORTANT: The output of IDs/credentials here must be saved as it will be required later

# 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

# Create Pexip CVI Application
# Create App
$App = New-PexTeamsCviApplication -AppDisplayName "$($PxBaseConnName)TeamsConn" -Confirm:$false
$AppId = $App.AppId

# Create App Certificate - the certificate validity period is defined via the -ValidityInMonths parameter passed to New-PexTeamsCviApplicationCertificateCredential
# New-PexTeamsCviApplicationCertificateCredential cmdlet creates a self signed certificate and uploads it to Microsoft Entra ID for use as a credential for the CVI app
Write-Host "### Create and save CVI App certificate password using a password manager ###"
$AppCertificatePath = $App | New-PexTeamsCviApplicationCertificateCredential -ValidityInMonths 24
$AppCertificatePath = $AppCertificatePath.Trim()

Write-Host
Write-Host
Write-Host "`n----------------------------------------`n"
Write-Host
Write-Host "### Save CVI App ID (use a password manager) ###"
Write-Host "### Save CVI App certificate ###"
Write-Host
Write-Host "`$AppId = `"$($AppId)`""
Write-Host "`$AppCertificatePath = `"$($AppCertificatePath)`""
Write-Host
Write-Host "`n----------------------------------------`n"
Write-Host
Write-Host

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

# Azure Bot for the CVI AppID
# Create bot (must be globally unique, and only needs to be created once - in any of your regions)
Register-PexTeamsCviApplicationBot -SubscriptionId $PxSubscriptionId -ResourceGroupName $PxBotResourceGroupName -BotName "$($PxBaseConnName)-TeamsBot" -AppId $AppId -Confirm:$false -Tag $tags

# Deploy Pexip Teams Connector admin consent web page
$AdminConsentUrl = Publish-PexTeamsAdminConsentWebSite -SubscriptionId $PxSubscriptionId -ResourceGroupName $PxBotResourceGroupName -PxBaseConnName $PxBaseConnName -AppId $AppId -SourceAddressPrefixes $PxConsentSourceAddressPrefixes -Confirm:$false -Tag $tags

# 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 -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 Teams Connector TLS certificate file password when prompted

# Please enter the password for the PFX Teams Connector TLS 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': ***************

# Generating the next steps summary (this assumes you are connected to Microsoft Graph and with an authenticated account for use with Azure Resource Manager)
#
# Setting subscription
Set-AzContext -SubscriptionId $PxSubscriptionId

# Getting IP configurations
if ($PxUsePrivateRouting) {
    $LB = Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName
    $ExtLB = $LB | Where-Object { $_.Name.EndsWith("-LB") }
    $IntLB = $LB | Where-Object { $_.Name.EndsWith("-INTLB") }
    $LBExtIPID = $ExtLB.FrontendIpConfigurations[0].PublicIpAddress.id
    $LBIntIP = $IntLB.FrontendIpConfigurations[0].PrivateIpAddress
    $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
    $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBExtIPID
    $publicIpAddress = $ConnectorPublicIP[0].IpAddress
    $privateIpAddress = $LBIntIP
} else {
    $LB = (Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName)[0]
    $LBPublicIPID = $LB.FrontendIpConfigurations[0].PublicIpAddress.id
    $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
    $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBPublicIPID
    $publicIpAddress = $ConnectorPublicIP[0].IpAddress
}

# Getting connection string for the newly deployed Event hub
$eventHub = (Get-AzResource -ResourceGroupName $PxTeamsConnStaticResourceGroupName -ResourceType Microsoft.EventHub/namespaces)[0]
$eventHubKey = Get-AzEventHubKey -Name "pexip_teams_connector_access" -NamespaceName $eventHub.Name -ResourceGroupName $eventHub.ResourceGroupName

# Printing next steps
Write-Host
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host "When the Teams Connector is deployed, you have to create a DNS A record for your hostname,"
Write-Host "then the Office 365 admin must consent for the CVI App Id to join Teams Meetings"
Write-Host
Write-Host "1) Set up a public DNS A record for $($PxTeamsConnFqdn) pointing to the Public IP of "
Write-Host "   the load balancer ($($publicIpAddress))"
Write-Host
Write-Host "2) Give consent to the CVI app. Go to: $AdminConsentUrl"
Write-Host
Write-Host "   If Management Consent Source Address prefixes are defined, the administrator"
Write-Host "   doing consent must come from one of these addresses (or subnets)."
Write-Host "   Consent address prefixes: $($PxConsentSourceAddressPrefixes)"
Write-Host
Write-Host "3) Update the Management Node setting 'Azure Event Hub connection string' for $($PxTeamsConnFqdn) to:"
Write-Host "    $($eventHubKey.PrimaryConnectionString)"
Write-Host
if ($PxUsePrivateRouting) {
    Write-Host "4) Set up a private DNS A record for $($PxTeamsConnFqdn) pointing to the (private) frontend IP of "
    Write-Host "   the internal load balancer ($($privateIpAddress))"
    Write-Host "   See: https://docs.pexip.com/admin/teams_routing.htm#enabling"
}
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 "33"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 33"}

# 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-win-2019-stig"
"offer"     = "cis-win-2019-stig"
"publisher" = "center-for-internet-security-inc"
"version"   = "latest"}

# Connect to Microsoft Graph, Azure Resource Manager account and import Pexip CVI module
# Microsoft Graph commands
# Connect to Microsoft Graph
# If AAD/365 admin account is not the same as Azure Resource Manager admin account,
# the next section is to be run by the AAD admin.
#
# IMPORTANT: The output of IDs/credentials here must be saved as it will be required later

# 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

# Create Pexip CVI Application
# Create App
$App = New-PexTeamsCviApplication -AppDisplayName "$($PxBaseConnName)TeamsConn" -Confirm:$false
$AppId = $App.AppId

# Create App Certificate - the certificate validity period is defined via the -ValidityInMonths parameter passed to New-PexTeamsCviApplicationCertificateCredential
# New-PexTeamsCviApplicationCertificateCredential cmdlet creates a self signed certificate and uploads it to Microsoft Entra ID for use as a credential for the CVI app
Write-Host "### Create and save CVI App certificate password using a password manager ###"
$AppCertificatePath = $App | New-PexTeamsCviApplicationCertificateCredential -ValidityInMonths 24
$AppCertificatePath = $AppCertificatePath.Trim()

Write-Host
Write-Host
Write-Host "`n----------------------------------------`n"
Write-Host
Write-Host "### Save CVI App ID (use a password manager) ###"
Write-Host "### Save CVI App certificate ###"
Write-Host
Write-Host "`$AppId = `"$($AppId)`""
Write-Host "`$AppCertificatePath = `"$($AppCertificatePath)`""
Write-Host
Write-Host "`n----------------------------------------`n"
Write-Host
Write-Host

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

# Azure Bot for the CVI AppID
# Create bot (must be globally unique, and only needs to be created once - in any of your regions)
Register-PexTeamsCviApplicationBot -SubscriptionId $PxSubscriptionId -ResourceGroupName $PxBotResourceGroupName -BotName "$($PxBaseConnName)-TeamsBot" -AppId $AppId -Confirm:$false -Tag $tags -TeamsEnvironmentName TeamsGCCHigh

# Deploy Pexip Teams Connector admin consent web page
$AdminConsentUrl = Publish-PexTeamsAdminConsentWebSite -SubscriptionId $PxSubscriptionId -ResourceGroupName $PxBotResourceGroupName -PxBaseConnName $PxBaseConnName -AppId $AppId -SourceAddressPrefixes $PxConsentSourceAddressPrefixes -Confirm:$false -Tag $tags

# 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 -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 Teams Connector TLS certificate file password when prompted

# Please enter the password for the PFX Teams Connector TLS 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': ***************

# Generating the next steps summary (this assumes you are connected to Microsoft Graph and with an authenticated account for use with Azure Resource Manager)
#
# Setting subscription
Set-AzContext -SubscriptionId $PxSubscriptionId

# Getting IP configurations
if ($PxUsePrivateRouting) {
    $LB = Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName
    $ExtLB = $LB | Where-Object { $_.Name.EndsWith("-LB") }
    $IntLB = $LB | Where-Object { $_.Name.EndsWith("-INTLB") }
    $LBExtIPID = $ExtLB.FrontendIpConfigurations[0].PublicIpAddress.id
    $LBIntIP = $IntLB.FrontendIpConfigurations[0].PrivateIpAddress
    $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
    $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBExtIPID
    $publicIpAddress = $ConnectorPublicIP[0].IpAddress
    $privateIpAddress = $LBIntIP
} else {
    $LB = (Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName)[0]
    $LBPublicIPID = $LB.FrontendIpConfigurations[0].PublicIpAddress.id
    $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
    $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBPublicIPID
    $publicIpAddress = $ConnectorPublicIP[0].IpAddress
}

# Getting connection string for the newly deployed Event hub
$eventHub = (Get-AzResource -ResourceGroupName $PxTeamsConnStaticResourceGroupName -ResourceType Microsoft.EventHub/namespaces)[0]
$eventHubKey = Get-AzEventHubKey -Name "pexip_teams_connector_access" -NamespaceName $eventHub.Name -ResourceGroupName $eventHub.ResourceGroupName

# Printing next steps
Write-Host
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host "When the Teams Connector is deployed, you have to create a DNS A record for your hostname,"
Write-Host "then the Office 365 admin must consent for the CVI App Id to join Teams Meetings"
Write-Host
Write-Host "1) Set up a public DNS A record for $($PxTeamsConnFqdn) pointing to the Public IP of "
Write-Host "   the load balancer ($($publicIpAddress))"
Write-Host
Write-Host "2) Give consent to the CVI app. Go to: $AdminConsentUrl"
Write-Host
Write-Host "   If Management Consent Source Address prefixes are defined, the administrator"
Write-Host "   doing consent must come from one of these addresses (or subnets)."
Write-Host "   Consent address prefixes: $($PxConsentSourceAddressPrefixes)"
Write-Host
Write-Host "3) Update the Management Node setting 'Azure Event Hub connection string' for $($PxTeamsConnFqdn) to:"
Write-Host "    $($eventHubKey.PrimaryConnectionString)"
Write-Host
if ($PxUsePrivateRouting) {
    Write-Host "4) Set up a private DNS A record for $($PxTeamsConnFqdn) pointing to the (private) frontend IP of "
    Write-Host "   the internal load balancer ($($privateIpAddress))"
    Write-Host "   See: https://docs.pexip.com/admin/teams_routing.htm#enabling"
}
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host

After deploying the (first) Teams Connector

  1. When the script ran, it generated some output that listed the CVI App ID and certificate path:

  2. Store the items as instructed:

    1. Store the CVI App ID and CVI App certificate password in a password manager. These variables are needed to redeploy the Teams Connector.
    2. Store the CVI App certificate PFX file in a safe location.

This means that if you need to run the redeploy script, you will not rerun the commands that imported the PowerShell module and created the app. Instead you will set the variables to the ID and certificate of the CVI app that you created the first time.

Upgrading or redeploying a Teams Connector that is already using CBA

You can follow most of the standard steps for upgrading and redeploying the Teams Connector. However, there are some variations to the process and scripts as described below.

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

In this section, step 4 is new and step 7 (previously step 6) has been updated to refer to assigning the $AppId and $AppCertificatePath variables.

  1. Download the latest relevant version of the Teams Connector ZIP file (Pexip_Infinity_Connector_For_Microsoft_Teams_v33.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 copies of the initialization and redeploy scripts. You should have created and stored your version of these scripts after you completed your initial installation of your first Teams Connector.

    If you are migrating (upgrading) an existing Teams Connector using password-authentication to CBA, use the initialization and redeploy scripts contained on this page.

  6. Check your saved copy of the initialization script that sets the environmental variables:

    • 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. Check your saved copy of the redeploy script:

    • 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 (further below) 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.
  8. As usual, remove and then recreate the dynamic resource group and ensure appropriate roles are assigned to the resource groups as described here.

Redeploy the Teams Connector

In this section you must use the new version of the redeploy script as provided below, which uses your certificate to authenticate the Teams Connector CVI application towards MS Graph.

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.

  • 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 "33"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 33"}

# 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 -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 "33"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 33"}

# 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-win-2019-stig"
"offer"     = "cis-win-2019-stig"
"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 -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.

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_v33.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 "33"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 33"}
    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.

    Note that:

    • The script passes a -ValidityInMonths parameter to the PexTeamsCviApplicationCertificateCredential cmdlet to specify the validity period of the 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 contained here.