[Index]

Model: relation/MicrosoftTenant

Microsoft UC Application Setup

Full HTML Help

MICROSOFT

Overview

To allow VOSS Automate to manage and provision Microsoft applications, VOSS Automate must be able to authenticate with Microsoft Entra, PowerShell proxy servers (one or more) Microsoft Teams, and Microsoft Exchange Online.

This task sets up the authentication between MS 365, MS Teams, and VOSS Automate, and sets up the PowerShell proxy server.

To access the flowcharts, view the topic via the release documentation at: https://documentation.voss-solutions.com/automate.html

"Network Communications External to the Cluster" in the VOSS Automate Installation Guide or Platform Guide.

Devices for Microsoft UC Application Setup

The table describes the devices configured for Microsoft UC application setup (authentication, authorization, and PowerShell proxy):

PowerShell Proxy Setup

Introduction

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

You will need to perform the following tasks:

1. Create Server-local Service Account
2. Configure Local Hosts File
3. Configure the Outbound Internet Proxy
4. Configure WinRM
5. Install Software Management Components on a PowerShell Proxy
6. Test Tenant Connection

Step 1: Create 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: Configure 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.

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

Step 3: Configure the Outbound Internet Proxy

This procedure configures a PowerShell Proxy server to use an outbound Internet proxy.

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.

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
   

Step 4: 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.

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}'

'10.1.1.10,psproxy01.domain.com'

'10.1.1.10,psproxy01.domain.com,psproxy.domain.com'

Step 5: Install Software Management Components

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

• Step 1: Install .NET Framework 4.8
• Step 2: Install Microsoft Teams PowerShell Module
• Step 3: Install Microsoft ExchangeOnlineManagement Module

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…"

Configure Microsoft Tenant Connection Parameters

Full HTML Help

This procedure configures the following connections:

• From Automate to the PowerShell Proxy
• Between the PowerShell Proxy and the tenant
• The Graph API connection between Automate and the tenant

Prerequisites:

You will need:

• The FQDN or IP address of a single-node PowerShell Proxy, or the FQDN corresponding to your load balancer’s virtual IP address. See PowerShell Proxy Setup

• The credentials for the local service account you created on the PowerShell Proxy

• Proxy authentication credentials (if the outbound Internet Proxy requires authentication)

  Note

  Authenticated proxy is not supported.

• The credentials for the Microsoft Teams tenant service account. See Create Microsoft Teams Service Account on Azure.

• The Client ID, Tenant ID, and, for authentication for MS Graph, the client secret and/or the certificate created when registering Automate as an application object with Microsoft Entra ID. See Create Application Registration in Tenant Portal.

• If you're using Automate to manage Microsoft Exchange online, you will need the certificate authentication thumbprint you generated on the Azure portal for Microsoft Exchange. See Create Application Registration in Tenant Portal.

To add and configure the Microsoft Tenant

1. Log in to the Automate Admin Portal as a Provider Administrator.

   Note

   By default, the Provider administrator role is the only role that has the ability to create Tenant connections.

2. Add the Microsoft tenant:

   1. Go to (default menus) Apps Management > Microsoft Tenant.
   2. Click Add.
   3. Choose the hierarchy level where you wish to add the tenant. Typically, this is at Customer level.
   4. Enter a name and a description for the tenant.

3. Add the PowerShell Proxy connection parameters:

   1. Locate the Microsoft Teams Powershell section.

   2. In the Host field, enter the FQDN or IP address of a single-node PowerShell Proxy, or the FQDN corresponding to your load balancer's virtual IP address.

      Note

      For details around the local hosts file and the TrustedHosts WinRM configuration, see PowerShell Proxy Setup.

   3. In the Username field and Password field, enter the credentials for the local service account you created on the PowerShell Proxy.

4. Configure the outbound internet Proxy:

   1. Locate the Microsoft Teams HTTP Proxy fields.

   2. If you have an outbound Internet Proxy deployed between the PowerShell Proxy and the public Internet, select the Use HTTP Proxy checkbox.

      Note

      • If there is no outbound Internet Proxy deployed between the PowerShell and the public internet, leave both checkboxes unchecked, and leave the Username and Password fields blank. Continue to the next step.
      • Authenticated proxy is supported.

   3. If the outbound Internet proxy requires authentication, select the Use HTTP Proxy Authentication checkbox, and enter the Proxy authentication credentials in the Username / Password fields.

      Note

      You will have already provisioned the outbound Internet Proxy's IP address (or FQDN) and port number when you set up the PowerShell Proxy. See PowerShell Proxy Setup, and note the caveat regarding proxy authentication in Deployment Topology Options.

5. Add the Microsoft Teams Tenant service account credentials:

   1. Locate the Microsoft Teams fields.

   2. In the Admin Username and Admin Password fields, enter the credentials for the Microsoft Teams tenant service account.

      Note

      You created this account earlier. See Create Microsoft Teams Service Account on Azure.

6. Add Microsoft 365 details to the Microsoft tenant:

   1. Locate the Microsoft 365 fields.

   2. Enter the Client ID and Tenant ID values recorded earlier during the application registration setup.

   3. If you're using client secret authentication, copy the secret value into the Secret field.

   4. If you're using certificate authentication:

      • Paste the certificate thumbprint obtained from Azure into the Certificate Thumbprint field.

        Note

        From release 21.4 onwards, this field is no longer a password, but plain text, since it is generated from the public portion of the certificate.

      • From the Certificate drop-down, choose the certificate previously created in the Admin Portal.

        Note

        • You uploaded the public key for this locally stored certificate to Azure. The thumbprint added in the Microsoft 365 tenant parameter is generated in Azure when the public key file is uploaded to Azure.
        • Certificate authentication only if a client secret is not provided.

   5. MS 365 proxy / MS 365 secure proxy: These fields allow for setting an outbound internet proxy server if required for traffic outbound to the public Internet. This proxy setup is used to define the route for the MS Graph API communications which the system uses for communication with the MS 365 cloud tenant.

      • If the Internet Proxy is not authenticated, then use the MS 365 proxy field and the format is:

        https://host:port/

      • If the Internet proxy requires authentication, then use the MS 365 secure proxy and the format is:

        https://proxyuser:proxypassword@host:port/

      In both cases the host can be a FQDN if resolvable via DNS or the IP address of the Internet proxy.

   6. Max page size for MSOLUser / Max page size for Groups: These fields control the paging size for the number of records pulled at a time from the corresponding API.

      • The MSOLUser setting controls the device/msgraph/MSOLUser related API.
      • The Group setting defines the number of records retrieved at one time from the device/msgraph/Group related APIs.

      When left blank, the default page size is 999, a high number that allows for best performance. It is recommended that you leave this blank and utilize the default value unless you encounter errors on your Microsoft 365 syncs (for example, "Template output exceeded memory limit"). In that case, you can enter a specific value less than 999 in order to try a smaller number of records until the sync no longer has an error.

      Note that reducing the value may impact sync performance so it is best to use the largest paging size that does not result in an error.

      From release 21.4-PB4 onwards, the memory limit handling of requests has been increased, so that any previous explicit specification of max page size values less than 999 may not be required anymore, or can be increased substantially.

7. If you're using Automate to manage Microsoft Exchange online, provision the Exchange Online application certificate thumbprint.

   Note

   The certificate authentication thumbprint is generated on the Azure portal for Microsoft Exchange. You would have installed this certificate on the PowerShell proxy server and configured it in the application registration.

   The certificate thumbprint is the encrypted password required for an authenticated connection to the Microsoft Cloud Exchange portal. Connecting to Microsoft Exchange is required to sync in the Microsoft Exchange objects (mailboxes, shared mailboxes, rooms, and distribution lists).

   1. Locate the Microsoft Exchange fields.

   2. Select Enable Microsoft Exchange.

   3. In the Certificate Thumbprint field, paste the certificate thumbprint you obtained earlier.

      Note

      You obtained the certificate thumbprint when logged into the PowerShell proxy to register the Automate application with Microsoft Entra ID. See Create Application Registration in Tenant Portal.

      The certificate thumbprint was created on the proxy and uploaded to the Azure portal. When generating PowerShell scripts to manage Microsoft Exchange Online, Automate includes this thumbprint so that the PowerShell proxy can use the corresponding certificate to authenticate with Microsoft Exchange Online.

8. Click Save.

9. Test your Microsoft tenant connection. You will be prompted to confirm the test.

   Note

   In this step you will verify that Automate can connect to the Microsoft Teams tenant using PowerShell, and to Microsoft Entra ID using the Microsoft Graph API.

   1. On the Microsoft Tenant page, choose the relevant tenant.
   2. Click Test Connection.

Modifying Microsoft Tenant

Modifying a Microsoft tenant will only overwrite those driver parameters in the underlying connections (MSTeamsOnline, MSExchangeOnline, MSGraph) which are managed by the tenant workflows. Other driver parameters will be left as is.

Next Steps

• Verify that no changes are needed in user name mapping macros prior to sync. High level administrators with access to the data/MultivendorUsernameMappingMacros model instances should carry out this task.

"username_macro_ms_365": [
   "{{ input.UserPrincipalName }}",
   "(( fn.is_none_or_empty input.username == fn.true ))<NOT_FOUND>(( data.User.username | username:input.username != '' ))<{{ data.User.username | username:input.username }}><NOT_FOUND>",
   "(( fn.is_none_or_empty input.username == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_365:input.username != '' ))<{{ data.User.username | username_ms_365:input.username }}><NOT_FOUND>",
   "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | email:input.UserPrincipalName != '' ))<{{ data.User.username | email:input.UserPrincipalName}}><NOT_FOUND>",
   "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_365:input.UserPrincipalName != '' ))<{{ data.User.username | username_ms_365:input.UserPrincipalName }}><NOT_FOUND>",
   "(( fn.is_none_or_empty previous.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_365:previous.UserPrincipalName != '' ))<{{ data.User.username | username_ms_365:previous.UserPrincipalName }}><NOT_FOUND>",
   "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_teams:input.UserPrincipalName != '' ))<{{ data.User.username | username_ms_teams:input.UserPrincipalName }}><NOT_FOUND>",
   "(( fn.is_none_or_empty previous.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_teams:previous.UserPrincipalName != '' ))<{{ data.User.username | username_ms_teams:previous.UserPrincipalName }}><NOT_FOUND>",
   "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( device.cucm.User.userid | userIdentity:input.UserPrincipalName != '' ))<{{ device.cucm.User.userid | userIdentity:input.UserPrincipalName }}><NOT_FOUND>",
   "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( device.cucm.User.userid | mailid:input.UserPrincipalName != '' ))<{{ device.cucm.User.userid | mailid:input.UserPrincipalName }}><NOT_FOUND>"
    ],

• Perform a sync from the Microsoft tenant to import Microsoft users, tenant dial plan, licenses, and policies to the customer level. You will be prompted to confirm the syncs.

  For Microsoft Exchange, ensure that instances for all 4 device models (User mailboxes, Shared Mailboxes, Room Mailboxes, and Distribution Mailboxes) are synced in at the level were the tenant exists.

• Configure the customer-wide site defaults doc (SDD), CUSTOMER_TEMPLATE. See Site Defaults Doc Templates.

• Add network device lists (NDLs) with Microsoft 365 and Microsoft Teams tenant details. NDLs are required when adding sites. See Configure a Network Device List.

• Create sites.

• Run the overbuild. See: Overbuild for Microsoft.

• Go to VOSS Automate Configuration and Sync

Related Topics

• Microsoft Quick Start

Microsoft Overview in the Core Feature Guide

Microsoft Sync Overview in the Best Practices Guide

This relation implements the workflows to manage Microsoft Tenant connection parameters and enabled services.

Model Details: relation/MicrosoftTenant