Model: relation/MicrosoftTenant

Microsoft Graph API

VOSS Automate uses the Microsoft Graph API (if available) to manage cloud-based applications, such as Microsoft Entra.

Windows PowerShell and PowerShell Proxy Servers

If the Microsoft Graph API is not available, and for on-premise applications, VOSS Automate uses Windows PowerShell, along with PowerShell management modules provided by Microsoft. In this case, VOSS Automate requires access to at least one Windows computer to use as the PowerShell proxy server.

VOSS Automate manages Microsoft Teams and Microsoft Exchange Online using the PowerShell proxy servers running Windows PowerShell. The PowerShell proxy servers execute remote PowerShell cmdlets.

The table describes how PowerShell Proxies may be used to manage on-premise or cloud-based applications:

Authentication and authorization may be enforced in two places:

• On the PowerShell proxy
• In the Microsoft 365 tenant

When using Windows PowerShell for Microsoft apps management, VOSS Automate creates separate PowerShell sessions via the PowerShell proxy servers for each Microsoft application being managed for a specific customer tenant or domain.

All PowerShell sessions for a particular customer may be hosted by the same PowerShell proxy server, or you can configure a separate PowerShell proxy server for each PowerShell session. Optionally, the PowerShell proxy servers hosting the PowerShell sessions may be dedicated for this purpose exclusively.

Related Topics

• PowerShell Proxy Setup

WinRM and WSMan

Windows Server includes the "Windows Remote Management" (WinRM) service, which implements the "Web Services-Management" protocol (WSMan):

• VOSS Automate connects to the WinRM service on the PowerShell proxy and provides credentials for an elevated local service account on that server
• The WinRM service executes commands from the set provided by the Microsoft Teams and Microsoft Exchange PowerShell modules.

Once connected, VOSS Automate pushes PowerShell scripts (which it generates "on the fly") to the PowerShell proxy, and instructs WinRM to execute the scripts and return the results. The Microsoft Teams and Exchange Online Management PowerShell modules (provided by Microsoft) then connect to the Microsoft 365 tenant.

Related Topics

• Configure WinRM

PowerShell Proxy Deployment Topologies

PowerShell Proxy Server Domain Membership

PowerShell proxy servers may be joined to a Microsoft Entra domain.

Domain membership is required if you're using VOSS Automate to manage or extract data from any on-premises component, such as Skype for Business Server, on-premises Microsoft Entra, or on-premises Exchange Server.

Domain membership is optional in all other scenarios.

Redundancy

Deploying two or more PowerShell proxy servers provides redundancy. PowerShell proxy servers can be scaled and made highly available by interposing a load balancer between VOSS Automate and the PowerShell proxy servers.

Load balancer requirements:

• Must forward incoming HTTP and HTTPS requests on TCP ports 5985 and 5986
• Must be configured in "IP Affinity" mode so 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 deploying VOSS Automate 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.

Related Topics

• Configure Local Hosts File

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.

Related Topics

• Configure the Outbound Internet Proxy

Microsoft Entra

VOSS Automate uses the Microsoft Graph API at https://graph.microsoft.com over TCP port 443 to interact with Microsoft Entra.

Microsoft's application registration process provides authentication and authorization services for VOSS Automate. For details, see Create Application Registration in Tenant Portal

You can configure the permissions granted to the VOSS Automate application 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).

For details around the permissions that VOSS Automate requires, see Step 3: Add Microsoft Graph API Permissions

Microsoft Teams

VOSS Automate uses the PowerShell proxy and the Microsoft Teams PowerShell module to manage Microsoft Teams end user, service, device policies, and telephony settings.

The PowerShell scripts authenticate to the Microsoft Teams tenant using Basic Authentication.

The PowerShell scripts authenticate using the credentials associated with a service account in the tenant. The tenant 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.

You must assign at minimum the following role to the service account used for managing Microsoft Teams:

Microsoft Exchange Online

VOSS Automate uses the PowerShell proxy server, along with Microsoft's Exchange Online PowerShell module, to manage MS Exchange Online user mailboxes, shared mailboxes, room mailboxes, and distribution groups.

VOSS Automate uses app-only authentication for Microsoft Exchange Online.

For app-only authentication, you will need to create an X.509 certificate with a private key. The certificate and private key must be installed on the PowerShell proxy server.

When registering the VOSS Automate Application Object with Microsoft Entra, you will upload the 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 so that VOSS Automate can pass the thumbprint to the PowerShell proxy. The PowerShell proxy uses the certificate identified by the thumbprint to authenticate with Exchange Online.

Microsoft Entra permission for managing Exchange Online

VOSS Automate requires the following Microsoft Entra permission to manage Exchange Online:

RBAC role for managing Exchange Online

VOSS Automate requires the following RBAC role for managing Exchange Online:

Azure Active Directory

VOSS Automate uses the Microsoft Graph API at https://graph.microsoft.com over TCP port 443 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 certificate identified by the thumbprint to authenticate with Exchange Online.

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

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

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.

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
   

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

Step 6: 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: Deployment Topology Options

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.

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 earlier. See Create Service Account for Microsoft Teams Management via PowerShell.

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