.. _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.