Microsoft Devices¶

Introduction¶

VOSS Automate can be used to manage multiple applications within Microsoft’s Unified Communications stack including Azure Active Directory, Microsoft Teams, and Exchange Online, and on-premises Active Directory, Skype for Business Server, and Exchange Server.

Where it is available, VOSS Automate utilizes the Microsoft Graph API to manage cloud-based applications such as Azure Active Directory. Where the Graph API is not available, and for on-premises applications, VOSS Automate uses Windows PowerShell along with Microsoft-provided PowerShell management modules. Because PowerShell is native to Microsoft Windows, VOSS Automate requires access to at least one Windows computer that will, in turn, execute remote PowerShell cmdlets on VOSS Automate’s behalf. In this document we will refer to these computers as “VOSS Automate PowerShell Proxies”, or simply “PS Proxies”. For management of on-premises applications the PS Proxy must be joined to the domain under management. This means that if you are using VOSS Automate to manage multiple on-premises customer domains you need at least one domain-joined PS Proxy for each of those domains. For cloud-based applications a PS Proxy can be used to manage multiple Microsoft 365 tenants. A PS Proxy that manages only cloud-based applications can optionally be configured as a workgroup server.

The Microsoft Graph API is the preferred choice when it is available due to its greater simplicity, lack of the need for an intervening proxy, lower latency, more secure authentication options, and more granular permissions management. As the Graph API matures, VOSS Automate can easily be updated to leverage new Graph functionality by adding new templates or updating existing ones. These template updates can be deployed with no downtime or service impact.

Where Graph is not available, VOSS Automate brings PowerShell into play. VOSS Automate creates, via a PS Proxy, a separate PowerShell session for each of the Microsoft applications being managed for a specific customer tenant or domain. All the PowerShell sessions for a particular customer may be hosted by the same PS Proxy, or you can configure a separate PS Proxy for each session. The PS Proxies hosting these PowerShell sessions may be dedicated for this purpose exclusively, but this is not required. PS Proxies can be scaled and made highly available by interposing a load balancer between VOSS Automate and the proxies.

Microsoft Authentication, Authorization, and Security Considerations¶

Note

For specific details regarding the URLs, ports, and protocols that VOSS Automate uses to connect to the PowerShell Proxy (described below) and to the Microsoft 365 tenant, and that the PowerShell Proxy uses to connect to the tenant, refer to:

Network Communications External to the Cluster.

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.

Permission	Description	Management Use Case
User.Read.All	Allows the app to read the full set of profile properties, group membership, reports and managers of other users in your organization.	List Azure AD Users Retrieve Azure AD user properties Retrieve Azure AD user license details
User.ReadWrite.All	Allows the app to read and write the full set of profile properties, group membership, reports and managers of other users in your organization. Also allows the app to create and delete non-administrative users. Does not allow reset of user passwords.	Update Azure AD user properties Update Azure AD user license assignment
Organization.Read.All	Allows the app to read the organization and related resources. Related resources include things like subscribed SKUs and tenant branding information.	List subscribed SKUs (subscribed, used, and available licenses) Retrieve subscribed SKU details, including service plans included in the SKU

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:

Role	Description	Management Use Case
Skype for Business Administrator	Full access to all Teams and Skype features, Skype user attributes, manages service requests, and monitors service health.	List Teams Users Retrieve Teams user identity, attributes, and assigned policies Update Teams user attributes and assigned policies Enable / disable Enterprise Voice for Teams users Create, read, update and delete Teams policies Create, read, update, and delete Teams Enterprise Voice configuration, including Voice Routing Policies, PSTN Usages, Voice Routes, PSTN Gateways, and Tenant Dialplans Create, read, update, and delete Teams Call Queues and Teams Auto Attendants Create, read, update, and delete Teams endpoints, including Teams Phones, Common Area Phones, Collaboration Bars, and Teams Rooms

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:

Permission / Role	Description
Azure AD permission: Exchange.ManageAsApp	Permission required for a registered application to access Exchange Online resources
RBAC Role: Exchange Administrator	Users with this role have global permissions within Microsoft Exchange Online. Also can create and manage all Microsoft 365 groups, manage support tickets, and monitor service health.

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.

Sign into the Azure portal using your Global Administrator credentials.
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.
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.
Under Manage select App registrations, then select New registration.
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.
Select Register.
Under Manage select Certificates & secrets.
Under Client secrets select New client secret. Enter a description and select an expiration, then click Add.
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.
Under Manage select API permissions, then select Add a permission.

Select Microsoft Graph.

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

Management Use Case	Required Permission
List Azure AD users	User.Read.All
Retrieve Azure AD user properties	User.Read.All
Retrieve Azure AD user license details	User.Read.All
Update Azure AD user properties	User.ReadWrite.All
Update Azure AD user license assignment	User.ReadWrite.All
List subscribed SKUs (subscribed, used, and available licenses)	Organization.Read.All
Retrieve subscribed SKU details, including service plans included in the SKU	Organization.Read.All

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.
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.
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.)
Under Manage select Manifest.
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.
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…”
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.
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.
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.
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).
On the Assignments page select Add assignments. On the Add assignments page search for and select your application.
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.

Sign into the Azure portal using your User Administrator credentials.
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.
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.
Select New user from the toolbar at the top of the page.
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”).
Create a password for the account.
Under Groups and roles select the default role (“User”, which is a live link).
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.
Click the Create button at the bottom of the page.

VOSS Automate 21.2