.. _pshell-proxy-setup:

PowerShell Proxy Setup
-----------------------

.. _21.3-PB1|VOSS-1072:


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: 

1. :ref:`conf-local-hosts-file`
2. :ref:`conf-outbound-internet-proxy`
3. :ref:`conf-winrm`
4. :ref:`install-software-components`
5. :ref:`test-tenant-connection`



.. _conf-local-hosts-file:

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**: 

1. 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

2. In the Notepad window uncomment the ``127.0.0.1`` line (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


.. _conf-outbound-internet-proxy:

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**:

1. 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
      ====================== =============================================


2. Open Windows Settings and go to **Network & Internet > Proxy**. 
3. Under **Manual proxy setup** enable **Use a proxy server**. 
4. In the **Address** field, fill out the IP address or FQDN of the outbound 
   Internet proxy server. 
5. 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. 
      
6. Select **Don't use the proxy server for local (intranet) addresses**. 

   .. image:: /src/images/MSFT_502dcf15c14207a8.png

7. Click **Save**.

   .. note::
   
      This is a per-user configuration, so ensure you sign in using the VOSS Automate 
      service account.


8. 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



.. _conf-winrm:

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**:

1. Open an elevated PowerShell session. 
2. 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-components:

Install Software Management Components
.........................................

This procedure installs the following software components on a new PowerShell Proxy server: 

* :ref:`install-step1`
* :ref:`install-step2`
* :ref:`install-step3`


.. rubric:: Before you start


The ``Install-Module`` command used in :ref:`install-step2` and 
:ref:`install-step3` 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…" 



.. _install-step1:

Step 1: Install .NET Framework 4.8
''''''''''''''''''''''''''''''''''''''

1. Browse to https://dotnet.microsoft.com. 
2. 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.

3. Download and run the .NET Framework 4.8 Runtime installer. 

   .. note:: 

      Once the installation completes, you may need to reboot the server. 



.. _install-step2:

Step 2: Install Microsoft Teams PowerShell Module
''''''''''''''''''''''''''''''''''''''''''''''''''''''

.. rubric:: 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).


1. Exit any existing PowerShell and PowerShell ISE windows. 
2. 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
           
3. 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.




.. rubric:: To install MS Teams PowerShell module on a new PowerShell proxy, perform this step:


1. From an elevated PowerShell session issue the following command:

   ::

      Install-Module MicrosoftTeams -RequiredVersion 4.3.0

   


.. _install-step3:

Step 3: Install Microsoft ExchangeOnlineManagement Module
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

1. 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-tenant-connection:

Test the Tenant Connection
...........................


This procedure tests the connection to Microsoft Teams from a 
non-privileged PowerShell session.

**Perform these steps**:

1. 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: :ref:`pshell-proxy-setup-deploy-topol`



2. 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. 

3. Verify that you have successfully connected to the tenant and retrieved one random user.