.. _microsoft-device-mgt: 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. .. _ms-auth-security: 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: .. raw:: html Network Communications External to the Cluster. .. raw:: latex the "Network Communications External to the Cluster" section of the VOSS Automate Installation Guide or Platform Guide. 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. .. tabularcolumns:: |p{4cm}|p{5cm}|p{6cm}| +------------------------+----------------------------------------+-------------------------------------------+ | Permission | Description | Management Use Case | +------------------------+----------------------------------------+-------------------------------------------+ | User.Read.All | Allows the app to read the full set of | * List Azure AD Users | | | profile properties, group membership, | * Retrieve Azure AD user properties | | | reports and managers of other users in | * Retrieve Azure AD user license details | | | your organization. | | +------------------------+----------------------------------------+-------------------------------------------+ | User.ReadWrite.All | Allows the app to read and write the | * Update Azure AD user properties | | | full set of profile properties, group | * Update Azure AD user license assignment | | | 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. | | +------------------------+----------------------------------------+-------------------------------------------+ | Organization.Read.All | Allows the app to read the | * List subscribed SKUs (subscribed, used, | | | organization and related resources. | and available licenses) | | | Related resources include things like | * Retrieve subscribed SKU details, | | | subscribed SKUs and tenant branding | including service plans included in the | | | information. | 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 :ref:`access-profile-operations`. .. _azure-AD-tenant-setup: 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. a. Select **Accounts in this organization only**. b. 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**. .. image:: /src/images/MSFT_4d57ce16a05261c5.png 9. Record the secret value in a safe location for use when setting up VOSS Automate. .. image:: /src/images/MSFT_bd385bd6a357b048.png .. 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**. .. image:: /src/images/MSFT_f24dc7cfff59dc11.png 11. Select **Microsoft Graph**. .. image:: /src/images/MSFT_e6d39996937914ef.png 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**. .. image:: /src/images/MSFT_dc4125b9da140c75.png 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 ============================================================================ ===================== 13. Under **Configured permissions** select **Grant admin consent for **. 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**. .. image:: /src/images/MSFT_50379baa9a20837f.png 14. If you will be using VOSS Automate to manage Exchange Online, complete the next section (:ref:`create-svc-acct-ms-teams-pshell`), then set up the PowerShell Proxy as described in :ref:`pshell-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**.  .. image:: /src/images/MSFT-manifest.png 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: .. image:: /src/images/MS-manifest-Before.png After: .. image:: /src/images/MS-manifest-After.png 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..." .. image:: /src/images/MS-config-not-granted-for.png 19. Select **Grant admin consent for **, and click **Yes**. Confirm that the status of **Exchange.ManageAsApp** has changed to "Granted for...".  .. image:: /src/images/MS-config-granted-for.png 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.  .. image:: /src/images/MS-upload-cert.png 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). .. image:: /src/images/MS-exchange-admin.png 23. On the **Assignments** page select **Add assignments**. On the **Add assignments** page search for and select your application. .. image:: /src/images/MS-add-assignments.png 24. Click **Add**. .. _create-svc-acct-ms-teams-pshell: 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.