PowerShell Proxy Setup¶
This procedure configures the PowerShell proxy servers and installs the Microsoft Teams PowerShell module.
Note
You must have local Administrator privileges on the PowerShell Proxy server to perform these steps.
You will need to perform the following tasks:
Configure PowerShell Proxy for Redundancy¶
Important
This task is only required if you’re deploying multiple PowerShell Proxy servers behind a load balancer. If you do not have any concerns around redundancy, you can skip this task.
This procedure adds a Fully Qualified Domain Name (FQDN) to the local hosts file on each PowerShell Proxy server you’re deploying. Each PowerShell Proxy server must be able to address itself with the FQDN corresponding to the load balancer’s virtual IP address.
Perform these steps:
On each of the PowerShell Proxy servers, open an elevated PowerShell window, and issue the following command:
PS C:\WINDOWS\system32> notepad C:\Windows\System32\drivers\etc\hosts
In the Notepad window uncomment the
127.0.0.1line (delete the hash) and append the FQDN of the load balancer virtual IP:
# Copyright (c) 1993-2009 Microsoft Corp.
#
# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
#
# This file contains the mappings of IP addresses to host names. Each
# entry should be kept on an individual line. The IP address should
# be placed in the first column followed by the corresponding host name.
# The IP address and the host name should be separated by at least one
# space.
#
# Additionally, comments (such as these) may be inserted on individual
# lines or following the machine name denoted by a '#' symbol.
#
# For example:
#
# 102.54.94.97 rhino.acme.com # source server
# 38.25.63.10 x.acme.com # x client host
# localhost name resolution is handled within DNS itself.
127.0.0.1 localhost psproxy.domain.com
# ::1 localhost
Configure the Outbound Internet Proxy¶
This procedure configures a PowerShell Proxy server to use an outbound Internet proxy.
Important
This step is only required if your deployment is using an outbound Internet proxy to access the public Internet (including Microsoft tenants).
Prerequisites:
If the outbound Internet proxy requires authentication, you will need to obtain those credentials and configure them in VOSS Automate (as described in the Core Feature Guide). The credentials are not configured directly on the PowerShell Proxy server.
Perform these steps:
Sign into the PowerShell Proxy server using the local service account that VOSS Automate will use to connect to the proxy.
Note
VOSS Automate must use a server-local service account for accessing the PowerShell Proxy server. It must not be a domain account (should the server be domain-joined). The service account must have the following properties:
Account Type
Local Computer Account (not a domain account)
Local Group Membership
Administrators
Remote Management Users
Open Windows Settings and go to Network & Internet > Proxy.
Under Manual proxy setup enable Use a proxy server.
In the Address field, fill out the IP address or FQDN of the outbound Internet proxy server.
In the Port field, fill out the port number required by the proxy.
Note
The port is typically 3128, but your organization may require a different port.
Select Don’t use the proxy server for local (intranet) addresses.
Click Save.
Note
This is a per-user configuration, so ensure you sign in using the VOSS Automate service account.
To make this configuration the default setting for all HTTP clients, open an elevated PowerShell session, and issue the following command:
netsh winhttp import proxy source=ie
Configure WinRM¶
This procedure configures the Windows Remote Management (WinRM) service with the appropriate settings for VOSS Automate.
VOSS Automate uses the Web Services-Management protocol (WSMan) to create the PowerShell sessions that manage Microsoft UC applications.
On Windows computers, the Windows Remote Management (WinRM) service implements WSMan.
You will need to configure WinRM on a PowerShell Proxy running on Windows Server 2019.
Note
Any firewalls between VOSS Automate and the PowerShell Proxy, including Windows Firewall on the proxy, must permit the connections listed in the following table, which describes WinRM Firewall Settings.
These firewall exceptions are enabled by default in Windows Server 2019.
Service |
Protocol |
Port |
|---|---|---|
WinRM 2.0 (HTTP) |
TCP |
5985 |
WinRM 2.0 (HTTPS) |
TCP |
5986 |
Perform these steps:
Open an elevated PowerShell session.
Issue the following commands:
Enable-WSManCredSSP -Role Server -Force
Enable-WSManCredSSP -Role Client -DelegateComputer \* -Force
Set-Item WSMan:\localhost\Service\AllowUnencrypted $true
Set-Item WSMan:\localhost\Service\Auth\Basic $true
Set-Item WSMan:\localhost\Client\AllowUnencrypted $true
Set-Item WSMan:\localhost\Client\Auth\Basic $true
Set-Item WSMan:\localhost\Client\TrustedHosts '{server identity}'
Note
When setting the TrustedHosts value, you’ll need to provide the identity of the server on which you’re executing these commands:
If this is a standalone PowerShell Proxy (not behind a load balancer), provide the server’s IP address and FQDN, with a comma between them.
If this PowerShell Proxy is behind a load balancer, append the FQDN of the load balancer’s virtual interface.
For example, assume the server’s FQDN is psproxy01.domain.com and its
IP address is 10.1.1.10. If the server is not behind a load balancer,
the value for TrustedHosts (including the quotes) will be:
'10.1.1.10,psproxy01.domain.com'
If the server is behind a load balancer, and the FQDN of the load
balancer’s virtual interface is psproxy.domain.com, then provide the following
value for TrustedHosts, including the quotes:
'10.1.1.10,psproxy01.domain.com,psproxy.domain.com'
Install Software Management Components¶
This procedure installs the following software components on a new PowerShell Proxy server:
Before you start
The Install-Module command used in Step 2: Install Microsoft Teams PowerShell Module and
Step 3: Install Microsoft ExchangeOnlineManagement Module downloads the specified PowerShell module
from the PowerShell Gallery (an online repository).
Since the
PowerShell Gallery has deprecated the use of TLS versions earlier than TLS 1.2, you will
need to force Windows PowerShell to use TLS 1.2, which will allow the Install-Module
command to work correctly. TLS 1.2 is the default in Windows Server 2019 and later.
If you’re using an earlier release of Windows Server, use the
following command to force PowerShell to use TLS 1.2:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
The command is relevant only for the current PowerShell session (its effect persists only
until you close the PowerShell window and end the session).
Errors such as the following when using the Install-Module command are likely the
result of a TLS version mismatch: “Unable to resolve package source”, “No
match was found…”
Step 1: Install .NET Framework 4.8¶
Browse to https://dotnet.microsoft.com.
Navigate to the download for .NET Framework 4.8 Runtime, or do an Internet search for “.NET Framework 4.8 download”.
Note
Ensure you only download from a URL ending in “microsoft.com”. The authenticity of software downloaded from third-party websites cannot be guaranteed.
Download and run the .NET Framework 4.8 Runtime installer.
Note
Once the installation completes, you may need to reboot the server.
Step 2: Install Microsoft Teams PowerShell Module¶
To upgrade any PowerShell proxies that have already been deployed, perform these steps:
Starting with VOSS Automate version 21.3-PB1, the required MS Teams PowerShell module v4.3.0. If you’re upgrading existing PowerShell proxy servers, perform the following steps (on each PowerShell proxy server) to use the supported version of the MS Teams module (v4.3.0).
Exit any existing PowerShell and PowerShell ISE windows.
From an elevated (run as Administrator) PowerShell window:
Stop-Service WinRM Uninstall-Module MicrosoftTeams Install-Module MicrosoftTeams -RequiredVersion 4.3.0 -AllowClobber Start-Service WinRM
Verify
Get-Module -ListAvailable -Name MicrosoftTeams
The output should show version 4.3.0
$cred = Get-Credential
Enter MS Teams tenant admin credentials in the pop-up.
Connect-MicrosoftTeams -Credential $cred Get-CsOnlineUser -ResultSize 1
The output should display the details for one random user.
To install MS Teams PowerShell module on a new PowerShell proxy, perform this step:
From an elevated PowerShell session issue the following command:
Install-Module MicrosoftTeams -RequiredVersion 4.3.0
Step 3: Install Microsoft ExchangeOnlineManagement Module¶
From an elevated PowerShell session issue the following command:
Install-Module -Name ExchangeOnlineManagement -RequiredVersion 2.0.5
Note
Check with VOSS in case a newer version of the ExchangeOnlineManagement module is recommended.
Test the Tenant Connection¶
This procedure tests the connection to Microsoft Teams from a non-privileged PowerShell session.
Perform these steps:
From a PowerShell session, configure a test session for an outbound Internet proxy (if your PowerShell Proxy server is behind an outbound Internet proxy that requires authentication):
$w = New-Object System.Net.WebClient $w.Proxy.Credentials = (Get-Credential) (when prompted, enter your outbound proxy credentials)
Note
The credentials you enter above persist only for the duration of this PowerShell session, and are deleted when you exit the PowerShell session.
See the caveat regarding proxy authentication, at: PowerShell Proxy Deployment Topologies
Issue the following command to test the connection to Microsoft Teams and to perform a test query:
Connect-MicrosoftTeams -Credential (Get-Credential) Get-CsOnlineUser -ResultSize 1 | Select DisplayName
When prompted, enter your Teams service account credentials.
Note
Perform step 1 first if your PowerShell Proxy is behind an outbound Internet proxy that requires authentication.
Verify that you have successfully connected to the tenant and retrieved one random user.