.. _microsoft-device-mgt:
Microsoft UC Application Setup
--------------------------------------------------
:bdg-primary:`Microsoft`
Overview
..........
To allow VOSS Automate to manage and provision Microsoft applications, VOSS Automate must
be able to authenticate with Microsoft Entra, PowerShell proxy servers (one or more)
Microsoft Teams, and Microsoft Exchange Online.
This task sets up the authentication between MS 365, MS Teams, and VOSS Automate, and sets up
the PowerShell proxy server.
.. note::
Microsoft changed the name of Azure Active Directory to Microsoft Entra ID in August 2023.
.. index:: Flowchart;VOSS Automate Authentication and Authorization for Microsoft
.. include:: microsoft-setup.uml
.. note::
For details around the URLs, ports, and protocols that VOSS Automate
uses to connect to the PowerShell proxy and the Microsoft 365
tenant, and which the PowerShell proxy uses to connect to the tenant, see:
.. raw:: html
Network Communications External to the Cluster
.. raw:: latex
"Network Communications External to the Cluster" in the VOSS Automate
Installation Guide or Platform Guide.
Devices for Microsoft UC Application Setup
.................................................
The table describes the devices configured for Microsoft UC application setup (authentication, authorization, and PowerShell proxy):
.. tabularcolumns:: |p{5cm}|p{10cm}|
+--------------------------+-------------------------------------------------------+
| **Device** | **Description** |
+--------------------------+-------------------------------------------------------+
| Microsoft Graph API | Used for managing cloud-based apps. VOSS Automate |
| | uses Microsoft Graph API to interact with Microsoft |
| | Entra. |
| | |
| | Registering VOSS Automate as an application object |
| | in Microsoft Entra provides authentication and |
| | authorization for VOSS Automate. |
+--------------------------+-------------------------------------------------------+
| PowerShell Proxy Servers | VOSS Automate accesses and provisions Microsoft |
| | Teams using PowerShell. |
| | |
| | Authentication and authorization are enforced on the |
| | PowerShell proxy and in the Microsoft 365 tenant. |
+--------------------------+-------------------------------------------------------+
| Microsoft Teams | VOSS Automate uses the PowerShell proxy server and |
| | the Microsoft Teams PowerShell module to manage MS |
| | Teams settings. |
| | |
| | PowerShell scripts authenticate to Microsoft Teams |
| | via an Application Registration. Basic Authentication |
| | and credentials associated with a service account in |
| | the tenant are used to Provision Resource Accounts in |
| | Microsoft Teams. |
+--------------------------+-------------------------------------------------------+
| Exchange Online | VOSS Automates uses the PowerShell proxy server and |
| | Microsoft Exchange Online PowerShell module to |
| | manage MS Exchange Online components. |
| | |
| | VOSS Automate authenticates using app-only |
| | authentication, which requires a certificate and |
| | private key installed on the PowerShell proxy. |
+--------------------------+-------------------------------------------------------+
Microsoft Graph API
''''''''''''''''''''''
VOSS Automate uses the Microsoft Graph API (if available) to
manage cloud-based applications, such as Microsoft Entra.
.. note::
When available, the Microsoft Graph API is the preferred choice, for
the following reasons:
* Greater simplicity
* Intervening proxy is not required
* Lower latency
* More secure authentication options
* More granular permissions management
As the Microsoft Graph API matures, VOSS Automate can easily
be updated to leverage new Graph functionality; new templates can be
added, and existing ones can be updated. Template updates can be deployed with
no downtime or service impact.
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:
========================== ===================================================
On-premise apps Join the PowerShell proxy server to the domain under management.
If using VOSS Automate to manage multiple
on-premises customer domains, add at least one
domain-joined PowerShell proxy for each domain.
Cloud-based apps Use a PowerShell proxy server to manage multiple Microsoft
365 tenants. A PowerShell proxy that manages only
cloud-based applications can optionally be
configured as a workgroup server.
========================== ===================================================
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.
.. rubric:: Related Topics
* :ref:`pshell-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.
.. rubric:: Related Topics
* :ref:`conf-winrm`
.. _pshell-proxy-setup-deploy-topol:
PowerShell Proxy Deployment Topologies
'''''''''''''''''''''''''''''''''''''''''''
.. rubric:: 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.
.. rubric:: Related Topics
* :ref:`conf-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.
.. rubric:: Related Topics
* :ref:`conf-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 :ref:`register-voss-app-in-azure`
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 :ref:`step3-add-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.
PowerShell scrips authenticate to Microsoft Teams via an Application Registration.
Basic Authentication and credentials associated with a service account in the tenant is used to
provision Resource Accounts in Microsoft Teams.
You must assign at minimum the following role to the service account used for managing
Microsoft Teams:
================================ ==========================================================================================================================
Role Description
================================ ==========================================================================================================================
Teams Administrator Provides full access to all MS Teams, manages service requests, and monitors service health.
Use cases:
- List MS Teams users
- Retrieve Teams user identity, attributes, and assigned policies
- Update MS Teams user attributes and assigned policies
- Enable / disable Enterprise Voice for MS Teams users
- Create, read, update and delete MS Teams policies
- Create, read, update, and delete MS Teams Enterprise Voice configuration, including Voice Routing Policies, PSTN Usages, Voice Routes, PSTN Gateways, and Tenant Dialplans
- Create, read, update, and delete MS Teams Call Queues and Teams Auto Attendants
- Create, read, update, and delete MS Teams endpoints, including Teams Phones, Common Area Phones, Collaboration Bars, and Teams Rooms
================================ ==========================================================================================================================
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.
.. note::
For more information about app-only authentication, see
`App-only authentication \| Microsoft Docs `_.
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. The certificate
can be created in Automate and used in the Microsoft tenant setup. Automate uploads the
certificate to the PowerShell proxy server and installs it. Automate also updates the thumbprint
in the tenant data. The public key is exported from Automate and imported into Microsoft Entra.
The certificate can also be imported into Automate from the customer.
When registering the Automate application object with Microsoft Entra, you'll upload the
certificate (with only the public key) and assign Exchange Online API permissions and an appropriate
RBAC role to the application.
.. rubric:: Microsoft Entra permission for managing Exchange Online
VOSS Automate requires the following Microsoft Entra permission to manage Exchange Online:
=============================================== =============================================
Microsoft Entra Description
=============================================== =============================================
Exchange.ManageAsApp Allows a registered application to access
Exchange Online resources
=============================================== =============================================
.. rubric:: RBAC role for managing Exchange Online
VOSS Automate requires the following RBAC role for managing Exchange Online:
=========================== ========================================================================
RBAC Role Description
=========================== ========================================================================
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.
=========================== ========================================================================
.. note::
For custom administrator user roles, ensure the associated Access Profile allows for all
operations on all MS Exchange models; that is: Access Profile type: ``device/msexchangeonline/*``
For details, see :ref:`access-profile-operations`.