Microsoft Authentication and Authorization Setup¶
Overview¶
To allow VOSS Automate to manage and provision Microsoft applications, VOSS Automate must be able to authenticate with Azure Active Directory, PowerShell proxy servers (one or more) Microsoft Teams, and Microsoft Exchange Online.
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:
Network Communications External to the ClusterAuthentication and Authorization Setup Workflow¶
The flowchart provides a high-level overview of the process to set up VOSS Automate authentication and authorization for managing Microsoft applications.
The table describes the devices configured for authentication and authorization:
Device |
Description |
Microsoft Graph API |
Used for managing cloud-based apps. VOSS Automate uses Microsoft Graph API to interact with Microsoft Azure Active Directory. Registering VOSS Automate as an application object in the Azure portal 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 scrips authenticate to Microsoft Teams using Basic Authentication, and credentials associated with a service account in the tenant. |
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 Azure Active Directory.
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.
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.
PowerShell Proxy Deployment Topologies¶
PowerShell Proxy Server Domain Membership
PowerShell proxy servers may be joined to an Active Directory 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 Active Directory, 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.
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.
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. For details, see VOSS Automate App Registration 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).
The table describes the permissions that VOSS Automate requires:
Permission |
Description |
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. Use cases:
|
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. Use cases:
|
Organization.Read.All |
Allows the app to read the organization and related resources. Related resources include things like subscribed SKUs and tenant branding information. Use cases:
|
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.
Note
The Microsoft Teams PowerShell module currently only supports 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.
Note
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 the service account to specific static IP addresses associated uniquely with your PowerShell proxy server(s).
For more information around Conditional Access, see What is Conditional Access in Azure Active Directory? | Microsoft Docs.
You must assign at minimum the following role to the service account used for managing Microsoft Teams:
Role |
Description |
|---|---|
Skype for Business Administrator |
Provides full access to all Teams and Skype features, Skype user attributes, manages service requests, and monitors service health. Use cases:
|
Exchange Online¶
VOSS Automate uses the PowerShell proxy server, along with Microsoft’s Exchange Online PowerShell module, to manage 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.
When registering the VOSS Automate Application Object with Azure AD, 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.
Azure AD permission for managing Exchange Online
VOSS Automate requires the following Azure AD permission to manage Exchange Online:
Azure AD permission |
Description |
|---|---|
Exchange.ManageAsApp |
Allows a registered application to access Exchange Online resources |
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 Access Profile Permissions and Operations.