Model: relation/MicrosoftTenant

Azure Active Directory

VOSS Automate uses the Microsoft Graph API at https://graph.microsoft.com over TCP port 44 to interact with Azure Active Directory. Microsoft's application registration process provides authentication and authorization services for VOSS Automate. Permissions granted to the VOSS Automate application can be fine-tuned based on the management use cases for which VOSS Automate has been designated. For example, you can grant permission to VOSS Automate to manage end user license assignments, or you can withhold that permission (in which case VOSS Automate will only be able to view existing license assignments, limiting the VOSS Automate workflows available to you). The table below identifies the permissions that VOSS Automate requires, and the use cases that each of those permissions enables.

PowerShell Proxy Server

VOSS Automate manages Microsoft Teams and Microsoft Exchange Online using one or more PowerShell Proxy servers running Windows PowerShell. Authentication and authorization are enforced in two places within this topology: on the PowerShell Proxy itself, and in the Microsoft 365 tenant.

Windows Server includes a service called "Windows Remote Management" (WinRM), which implements the "Web Services-Management" protocol (WSMan). VOSS Automate connects to the Windows Remote Management (WinRM) service on the PS Proxy and then uses that service to execute commands from the set provided by the Microsoft Teams and Microsoft Exchange PowerShell modules.

To connect to the WinRM service on the PS Proxy, VOSS Automate provides credentials for an elevated, local service account on that server. Once connected, VOSS Automate pushes PowerShell scripts that it generates "on the fly" to the PS Proxy, then instructs WinRM to execute those scripts and return the results. The Microsoft-provided "Microsoft Teams" and Exchange Online Management PowerShell modules, in turn, connect to the Microsoft 365 tenant.

**Microsoft Teams **

VOSS Automate manages Microsoft Teams end user, service, and device policies and telephony settings using the PowerShell Proxy server described above, along with Microsoft's Teams PowerShell module.

When the PowerShell scripts need to authenticate to the Microsoft Teams tenant, they do so using Basic Authentication, which is the only authentication mechanism currently supported by the Microsoft Teams PowerShell module. The scripts authenticate using the credentials associated with a service account in the tenant. That service account must be granted sufficient privileges to perform Microsoft Teams end user, service, and device management, and it must not have multi-factor authentication enabled.

To enhance the security of the connection between the PowerShell Proxy server(s) and your Microsoft Teams tenant, you may wish to consider using Conditional Access to restrict management access by that service account to specific static IP addresses associated uniquely with your PowerShell Proxy server(s).

For more information regarding Conditional Access refer to

What is Conditional Access in Azure Active Directory? | Microsoft Docs.

The service account used to manage Microsoft Teams must be assigned, at a minimum, the following role:

Exchange Online

VOSS Automate manages Exchange Online user mailboxes, shared mailboxes, room mailboxes, and distribution groups using the PowerShell Proxy server described above, along with Microsoft's Exchange Online PowerShell module. For authentication, VOSS Automate utilizes app-only authentication as described in App-only authentication | Microsoft Docs.

This authentication method requires the creation of an X.509 certificate with a private key, both of which are installed on the PowerShell Proxy. When registering the VOSS Automate Application Object with Azure AD as described below, you will upload that certificate (with only the public key) and assign Exchange Online API permissions and an appropriate RBAC role to the application. You will then provision the certificate's thumbprint in VOSS Automate. VOSS Automate passes that thumbprint to the PowerShell proxy, which in turn uses the thumbprint to authenticate with Exchange Online.

The table below identifies the application permission and RBAC role that VOSS Automate requires for Exchange Online management.

For custom administrator user roles, ensure the associated Access Profile allows for all operations on all MS Exchange models, in other words, Access Profile type: device/msexchangeonline/*. For details, see Access Profile Permissions and Operations.

Azure Active Directory Tenant Setup for VOSS Automate Application Registration

For VOSS Automate to use Microsoft Graph to access Azure Active Directory, you will have to register an Application Object with Azure AD. The Application Object describes VOSS Automate to Azure AD and can be considered the definition of the VOSS Automate application. This definition allows the Azure AD service to issue authentication tokens to the VOSS Automate service.

Be prepared to record three important pieces of information as you proceed through these steps. You will need all three of these values later, when you set up the tenant connection on VOSS Automate.

• Your Directory (tenant) ID (labelled Tenant ID in VOSS Automate)
• Your Application (client) ID (labelled Client ID in VOSS Automate)
• Your Client secret (labelled Secret in VOSS Automate)

You can retrieve your Tenant and Client IDs from your Azure Active Directory portal at any time. Your Client secret will be exposed only once, as noted below, so be sure to save that value in a secure location at that time. (As an analogy it may be useful to think of the combination of your Tenant ID and Client ID as if it were a login name, and your Client secret as if it were a password. From a security perspective you should treat these values as if they were administrative login credentials.)

You will have to be signed in as a Global Administrator to complete the following steps.

1. Sign into the Azure portal using your Global Administrator credentials.

2. If you have access to multiple tenants, use the Directory + Subscription filter in the top toolbar to select the tenant in which you wish to register the VOSS Automate application.

3. Select Azure Active Directory under Favorites in the navigation bar. If Azure Active Directory is not listed under your Favorites, select All services and then search for and select Azure Active Directory.

4. Under Manage select App registrations, then select New registration.

5. Enter a name for your application, for example "VOSS Automate". Users of your application might see this name. You can change it later.

   1. Select Accounts in this organization only.
   2. Ignore the Redirect URI section.

6. Select Register.

7. Under Manage select Certificates & secrets.

8. Under Client secrets select New client secret. Enter a description and select an expiration, then click Add.

9. Record the secret value in a safe location for use when setting up VOSS Automate.

   Important

   This is your only opportunity to save the secret value. Once you leave this screen you will no longer be able to retrieve it. If you lose this secret value you will have to delete the secret and repeat the steps for creating a new client secret.

10. Under Manage select API permissions, then select Add a permission.

11. Select Microsoft Graph.

12. Select Application permissions. Referring to the table below, select only the permissions associated with the use cases for which you wish to enable VOSS Automate management. Once you have selected all the relevant permissions, click Add permissions.

Azure Active Directory – Minimum Required Permissions

13. Under Configured permissions select Grant admin consent for <your tenant>. Answer Yes to the confirmation prompt at the top. Note that the status of each of the listed permissions has changed from Not granted to Granted.

14. If you will be using VOSS Automate to manage Exchange Online, complete the next section (Create Service Account for Microsoft Teams Management via PowerShell), then set up the PowerShell Proxy as described in PowerShell Proxy Setup.

    After you have set up the PowerShell Proxy return here and continue with the next step.

15. Return to the app page for your application. (If you have navigated away from there, or if you have had to log in again, you can find that page by selecting Azure Active Directory from your dashboard's All services page, then under Manage selecting App registrations, then selecting your application from the Owned applications tab.)

16. Under Manage select Manifest.

17. In the manifest page that opens, scroll down until you locate the line containing the word requiredResourceAccess. Place your cursor at the beginning of the very next line and paste the following text at that location:

    {
      "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
      "resourceAccess": [
     {
    "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
    "type": "Role"
     }
      ]
    },
    

    Before:

    After:

    When you are finished, click Save. Stay on the Manifest page.

18. Under Manage select API permissions. Verify that your previously-configured Microsoft Graph permissions are still present, and that Exchange.ManageAsApp now appears. Also note that the status of Exchange.ManageAsApp is currently "Not granted for..."

19. Select Grant admin consent for <your tenant>, and click Yes. Confirm that the status of Exchange.ManageAsApp has changed to "Granted for...".

    Leave this page open as we will return to it later.

20. Sign into the PowerShell Proxy using the service account that you created for VOSS Automate and open an elevated PowerShell window. In that window you will create and install on the proxy a self-signed certificate with private key. You will then export the certificate without its private key. Use the following PowerShell commands to accomplish this:

    # 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
    
    # Export the certificate to a .cer file
    $mycert | Export-Certificate -FilePath "$($env:USERPROFILE)\mycert.cer"
    
    # Extract the certificate thumbprint
    $mycert.Thumbprint
    

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

21. You will now upload the certificate you just exported in the previous step to Azure. Make sure the .cer file you created is accessible, then from the Azure Active Directory page where you left off, under Manage select Certificates & secrets.

    Under Certificates select Upload certificate, then on the Upload certificate page navigate to your exported certificate.

    Click Add.

22. Navigate back to your Azure Active Directory Overview page (select Azure Active Directory from All services. Under Manage select Roles and administrators. Scroll down the list of roles until you reach Exchange administrator. Click on the name (not the checkbox).

23. On the Assignments page select Add assignments. On the Add assignments page search for and select your application.

24. Click Add.

Create Service Account for Microsoft Teams Management via PowerShell

In this procedure we will create the service account that the PowerShell Proxy will use when performing Microsoft Teams management activities using PowerShell.

When setting up the connection parameters in VOSS Automate you will need the user name, domain name, and password that you specify in this procedure.

At a minimum you will need the "User administrator" role to complete this procedure.

1. Sign into the Azure portal using your User Administrator credentials.
2. If you have access to multiple tenants, use the Directory + Subscription filter in the top toolbar to select the tenant in which VOSS Automate will be managing Microsoft Teams.
3. Select Users under Favorites in the navigation bar. If Users is not listed under your Favorites, select All services and then search for and select Users.
4. Select New user from the toolbar at the top of the page.
5. Select the Create user radio button at the top of the page. Enter the username in the User name field (e.g. "voss4uc-svc") and select a domain. You may select any domain in the drop-down list, including the default "*.onmicrosoft.com" domain. Enter a name in the Name field (e.g. "VOSS Automate Service Account").
6. Create a password for the account.
7. Under Groups and roles select the default role ("User", which is a live link).
8. In the Directory roles popup search for "Skype". Check the checkbox to the left of Skype for Business Administrator, then click Select at the bottom of the popup.
9. Click the Create button at the bottom of the page.

PowerShell Proxy Server Domain Membership

PowerShell Proxy servers may be joined to an Active Directory domain. If you are using VOSS Automate to manage or extract data from any on-premises component, such as Skype for Business Server, on-premises Active Directory, or on-premises Exchange Server, then domain membership is required. In all other cases domain membership is optional.

Redundancy

You can deploy two or more PowerShell Proxy servers to provide redundancy. This configuration requires a load balancer (not provided by VOSS) between VOSS Automate and the PowerShell Proxy servers. If you choose this topology option, be aware of the following load balancer configuration requirements:

• The load balancer must forward incoming HTTP and HTTPS requests on TCP ports 5985 and 5986.
• The load balancer must be configured in "IP Affinity" mode, such that all incoming requests from a specific IP address are preferentially routed to the same PowerShell Proxy. This is done to maintain the integrity of HTTP sessions that can consist of multiple HTTP requests.

When VOSS Automate is deployed as a multi-node cluster and the load balancer is configured in "IP Affinity" mode, each Unified Node will have all its requests routed to the same PowerShell Proxy. A properly configured load balancer will distribute the overall load from all the Unified Nodes across the deployed PowerShell Proxy servers. When a PowerShell Proxy goes out of service the load balancer will route incoming traffic to the surviving servers, bypassing the failed one.

Outbound Internet Proxy

Some organizations require all traffic outbound to the public Internet - including traffic to Microsoft 365 tenants - to traverse an outbound Internet proxy server for audit logging and, optionally, authentication. This document describes the configuration in VOSS Automate and on the PowerShell Proxy server(s) that are required to support this topology option.

Service Account

VOSS Automate utilizes a single service account for access to the PowerShell Proxy. This account must be a server-local account (as opposed to a domain account, should the server be domain-joined), and must have the following properties:

VOSS Automate PowerShell Proxy Configuration

VOSS Automate utilizes the Web Services-Management protocol (WSMan) to create the PowerShell sessions used to manage Microsoft UC applications. On Windows computers, WSMan is implemented by the Windows Remote Management (WinRM) service.

This section defines how to configure WinRM on a PowerShell Proxy running on Windows Server 2019.

Local hosts File Configuration

If you are not deploying multiple PowerShell Proxy servers behind a load balancer, you may skip this step.

If you are deploying multiple PowerShell Proxy servers with a load balancer, each of the PowerShell Proxy servers must be able to address itself with the Fully Qualified Domain Name (FQDN) corresponding to the load balancer's virtual IP address. You can accomplish this by adding that FQDN to the local hosts file on each of the PowerShell Proxy servers. To do this, 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 (delete the hash) the 127.0.0.1 line 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

Outbound Internet Proxy Configuration

If your deployment does not require the use of an outbound Internet proxy to access the public Internet (including Microsoft tenants), skip this step.

Before attempting to deploy a PowerShell Proxy behind an outbound Internet proxy, please note the important caveat regarding proxy authentication in the Deployment Topology Options section above.

To configure a PowerShell Proxy server to use an outbound Internet proxy, configure the proxy as described in this section.

1. Sign into the PowerShell Proxy server using the local service account that VOSS Automate will use to connect to the proxy.

   Note

   The requirements for this account are described in the previous section.

   Open Windows Settings and select Network & Internet, then select Proxy from the navigation bar. Under Manual proxy setup flip the Use a proxy server switch to On. In the Address text box enter the IP address or FQDN of the outbound Internet proxy server. In the Port box enter the port number required by the proxy – typically 3128, but your organization may require a different port. Check the Don't use the proxy server for local (intranet) addresses checkbox. Click Save.

   Note

   • This is a per-user configuration, so be sure sign in using the VOSS Automate service account before performing this step.
   • The outbound Internet proxy may require authentication. If it does, obtain those credentials and configure them in VOSS Automate as described in the Provider Core Feature Guide. You will not configure those credentials directly on the PowerShell Proxy server.

   Outbound Proxy Setup

2. Make this the default setting for all HTTP clients by issuing the following command from an elevated PowerShell session:

   netsh winhttp import proxy source=ie
   

WinRM Configuration

Configure WinRM with the appropriate settings for VOSS Automate by issuing the following commands from an elevated PowerShell session.

'10.1.1.10,psproxy01.domain.com'

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

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

Firewall Settings

Any firewalls between VOSS Automate and the PowerShell Proxy, including Windows Firewall on the proxy, must permit the connections listed in the table below.

WinRM Firewall Settings

Installing the Management Software on a New PowerShell Proxy

The following software components must be installed on the PowerShell Proxy server. Install these components in the order listed.

TLS Version Mismatch Error and Resolution

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

• .NET Framework 4.8

  Browse to https://dotnet.microsoft.com and navigate to the download for .NET Framework 4.8 Runtime or do an Internet search for ".NET Framework 4.8 download". Download and run the .NET Framework 4.8 Runtime installer. Following installation, a reboot of the server will likely be required.

  Important

  Be sure to download only from a URL ending in "microsoft.com". Do not download software from any third-party web site as the authenticity of that software cannot be guaranteed.

• Microsoft Teams PowerShell Module

  From an elevated PowerShell session issue the following command:

  Install-Module MicrosoftTeams -RequiredVersion 2.0.0
  

Test Your Tenant Connection

You can test your ability to connect to Azure Active Directory by performing the following procedure from a non-privileged PowerShell session.

Configure Your Test Session for Outbound Internet Proxy

If your PowerShell Proxy server is behind an outbound Internet proxy that requires authentication, issue the following commands from your PowerShell session (but note the caveat regarding proxy authentication in the Deployment Topology Options section above):

$w = New-Object System.Net.WebClient

$w.Proxy.Credentials = (Get-Credential) (when prompted, enter your
outbound proxy credentials)

Keep this window open for the remainder of this section.

Test Connection to Microsoft Teams

Connect to Microsoft Teams and do a test query by issuing the following commands. If your PowerShell Proxy is behind an outbound Internet proxy that requires authentication, first refer to the steps at the beginning of this section.

When prompted, enter your Teams service account credentials.

Connect-MicrosoftTeams -Credential (Get-Credential)
Get-CsOnlineUser -ResultSize 1 \| Select DisplayName

The above commands should successfully connect to the tenant and retrieve one random user.

VOSS Automate Microsoft Connection Parameters

In this section we will provision the connections from VOSS Automate to the PowerShell Proxy, and from the PowerShell Proxy and your tenant. We will also provision the Graph API connection between VOSS Automate and the tenant.

1. Sign into VOSS Automate as a Provider Administrator (the only role that, by default, has the ability to create Tenant connections).

2. Go to (default menus) Apps Management > Microsoft Tenant.

3. Click the Add icon and select the hierarchy level where you wish to add the tenant. This will typically be at the customer level.

4. Enter a name and a description for this tenant.

   Next steps: Provision the PowerShell Proxy connection parameters.

Provision the PowerShell Proxy Connection Parameters

1. On the Microsoft Tenant page, locate the Microsoft Teams Powershell fields.

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

   Refer to the notes regarding the local hosts file and the TrustedHosts WinRM configuration in the VOSS Automate PowerShell Proxy Configuration section above.

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

   Next steps: Provision the outbound internet proxy configuration.

Provision the Outbound Internet Proxy Configuration

1. On the Microsoft Tenant page, locate the Microsoft Teams HTTP Proxy fields.

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

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

3. If the outbound Internet proxy requires authentication, select the Use HTTP Proxy Authentication checkbox, and enter the proxy authentication credentials in the Username and 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. Refer to the VOSS Automate PowerShell Proxy Configuration section above. Also please note the caveat regarding proxy authentication in the Deployment Topology Options section above.

   Next steps: Provision the Microsoft Teams tenant service account credentials.

Provision the Microsoft Teams Tenant Service Account Credentials

1. On the Microsoft Tenant page, locate the Microsoft Teams fields.

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

   You created this account in the Create Service Account for Microsoft Teams Management via PowerShell section, above.

   Next steps: Provision the Azure Active Directory Application Registration Parameters

Provision the Azure Active Directory Application Registration Parameters

In the Azure Active Directory Tenant Setup for VOSS Automate Application Registration section above you registered your VOSS Automate application. You should have captured the "Secret" value at that time.

If you did not capture your Client ID and Tenant ID, you can do so at any time from the Azure AD portal.

In this section, you will need to:

• Obtain Client ID and Tenant ID from the Azure AD Portal
• Add Microsoft 365 Details to the Microsoft Tenant