Set up the PowerShell Proxy Server

When setting up the UC apps, you’ll need to set up the PowerShell proxy server for Microsoft Teams, and (optionally) set up the PowerShell proxy server for Microsoft Exchange Online.

Before you start

• Configure Windows Remote Management (WinRM) Service

Related Topics

Step 1: Microsoft UC Application Setup

Set up the PowerShell proxy server for MS Teams

This procedure configures the PowerShell proxy server and installs the Microsoft Teams PowerShell module.

Note

You can set up a new PowerShell proxy server, or use an existing one.

You will need to perform the following tasks (as shown in the diagram):

1. Step 1: Create a server-local service account

2. Step 2: (Optional) Configure the PowerShell proxy for redundancy

3. Step 3: (Optional) Configure the outbound internet proxy

4. Step 4: Install software management components

5. Test the PowerShell Proxy Connection to the Tenant

Note

• You must have local Administrator privileges on the PowerShell Proxy server.

• A single PowerShell server can be used by multiple tenants, with or without Microsoft Exchange.

• Although optional, it is recommended that you install the ExchangeOnlineManagement module on the PowerShell proxy server.

Step 1: Create a server-local service account

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

This task is mandatory.

1. Create a local service account with the following properties:

   Account Type	Local Computer Account (not a domain account)
   Local Group Membership	Administrators Remote Management Users

2. Sign out of the server, then sign back in using the credentials for the service account you just created. Perform the remainder of the tasks in this section using this account.

Step 2: (Optional) Configure the PowerShell proxy for redundancy

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.

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.

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
   

Step 3: (Optional) 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.

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, then click Save.

   Note

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

   

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

Step 4: Install software management components

This procedure installs software components on a PowerShell Proxy server:

• Step 4.1: Install .NET Framework 4.8

• Step 4.2: Install Microsoft Teams PowerShell Module

• Install the Microsoft ExchangeOnlineManagement module

Before you start

The Install-Module command used in Step 4.2: Install Microsoft Teams PowerShell Module and Install the 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 4.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.

Step 4.2: Install Microsoft Teams PowerShell Module

There are two options for installing the MS Teams PowerShell module, depending on whether you’re upgrading PowerShell proxies that have already been deployed, or if you’re installing the MS Teams PowerShell module on a new PowerShell proxy:

Important

Starting with VOSS Automate version 21.4-PB3, the required MS Teams PowerShell module is v5.6.0. If you notice errors with this version, check with VOSS around using an alternative version.

1. Install the MS Teams PowerShell module. Choose an option:

   • UPGRADING?

     If you’re upgrading any existing PowerShell proxy servers that have already been deployed, perform these steps (on each PowerShell proxy server) to use the supported version of the MS Teams module:

     • 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 5.6.0 -AllowClobber
       Start-Service WinRM
       

     • Verify the version you’re using, (e.g. 5.6.0):

       Get-Module -ListAvailable -Name MicrosoftTeams
       

   • NEW INSTALL?

     If you’re installing the MS Teams PowerShell module on a new PowerShell proxy, run the following command from an elevated PowerShell session:

     Install-Module MicrosoftTeams -RequiredVersion 5.6.0
     

2. Test the connection to the MS Teams PowerShell module:

   Connect-MicrosoftTeams -Credential $cred
   Get-CsOnlineUser -ResultSize 1 | Select DisplayName
   

   Note

   You’ll need to enter your MS Teams tenant admin credentials. The output confirms your connection to the model (CsOnlineUser), and performs a test query.

Related Topics

• Test the PowerShell Proxy Connection to the Tenant

(Optional) Set up the PowerShell proxy server for MS Exchange Online

This procedure sets up the PowerShell proxy server for Microsoft Exchange.

Note

This task is only required if you’re using Exchange Online. However, while Exchange is an optional setup on the PowerShell proxy server, it is recommended best practice to install the ExchangeOnlineManagement module.

The diagram for this procedure includes the following tasks:

1. Install the Microsoft ExchangeOnlineManagement module

2. Generate and export certificate. See Create, install, and export the self-signed certificate

Once MS Exchange is set up on the PowerShell proxy server, you’ll need to enable Exchange management in the tenant portal. This involves:

• Adding Exchange ManageAsApp API permission to the application registration. See Step 1: Configure the manifest and update API permissions

• Importing the certificate generated on the PowerShell proxy, and assigning the Exchange Administrator role to the application registration. See Step 2: Upload certificate and add the application to the Exchange administrator role

Install the Microsoft ExchangeOnlineManagement module

Note

This is an optional task, required only if you’re using Exchange Online.

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

   Install-Module -Name ExchangeOnlineManagement -RequiredVersion 3.2.0
   

   Note

   Check with VOSS in case a newer version of the ExchangeOnlineManagement module is recommended.

Create, install, and export the self-signed certificate

On the PowerShell Proxy, you will need to create and install a self-signed certificate with a private key, and then export the certificate without its private key.

Note

This is an optional task, required only if you’re using Exchange Online.

1. Sign into the PowerShell Proxy ensuring that you use the service account you created for VOSS Automate (e.g. WSMan-svc). (This ensures the certificate is created and stored in the right account.)

2. Open an elevated PowerShell window.

3. Use the following PowerShell commands:

   To create the certificate and install in the current user store:

   $mycert = New-SelfSignedCertificate -DnsName 'your public domain' -CertStoreLocation 'cert:\CurrentUser\My' -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
   

   Note

   In place of ‘your public domain’, update the text with your ‘public domain’

   Example:

   $mycert = New-SelfSignedCertificate -DnsName 'voss-solutions.com' -CertStoreLocation 'cert:\CurrentUser\My' -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
   

   To export the certificate to a .cer file:

   $mycert | Export-Certificate -FilePath "$($env:USERPROFILE)\mycert.cer"
   

   To extract the certificate thumbprint:

   $mycert.Thumbprint
   

   Note

   The PowerShell command to extract the certificate thumbprint displays the certificate thumbprint. You will need this value when setting up the connection parameters in VOSS Automate, so copy it, and save it for later.