[Index]

Model: relation/MicrosoftTenant

Microsoft Tenant Setup

Full HTML Help

Overview

MICROSOFT PROVIDER ONLY

When Microsoft services and users are deployed in your system, a Microsoft tenant must be set up for each Microsoft customer in the system. The Microsoft tenant workflows create default schedules, data syncs, and test connections, based on the solution capabilities enabled for the tenant.

Solutions and the Microsoft tenant

Solutions are licensed system components delivering specific functionality and features. As at release 25.3, for new and upgrading customers, the following solutions are available in the system and enabled by default in the Global Settings:

• UC Automation
• Email

Deployment of the following solution capabilities is reserved for future development:

• UC Monitoring
• UC Analytics
• Security
• License Management
• Meetings Rooms

Inquire with your VOSS service representative for further details about the deployment and use of the reserved for development solutions.

Permissions required in the app registration for the Microsoft tenant, by solution:

• UC Automation: Certificate
• Email: Certificate
• UC Monitoring: Secret
• UC Analytics: Secret
• Security: Certificate
• License Management: Certificate
• Meetings Rooms: Certificate

Add a Microsoft tenant

This procedure adds and configures a Microsoft tenant at the customer level with one or more solution capabilities, including configuration of a single, customer configurable app registration containing all permissions associated with the selected solutions.

These steps also configure connections:

• Between Automate and the PowerShell Proxy
• Between the PowerShell Proxy and the Microsoft tenant
• The Graph API connection between Automate and the Microsoft tenant

Prerequisites:

• Solution capabilities required on the customer tenant must be enabled in the Global Settings.

• Proxy authentication credentials (if the outbound Internet Proxy requires authentication). Note that Authenticated proxy is not supported.

• The client ID and tenant ID

• Either the client secret or certificate. See Solutions and the Microsoft tenant. A secret or certificate created when registering Automate as an application object with Microsoft Entra ID. For greater security, certificate is preferred.

  If an Arbitrator is configured on Automate, secret is required.

See Arbitrators in the Core Guide

To add and configure the Microsoft Tenant

1. Log in to the Admin Portal as a Provider administrator.

   Note

   By default, the Provider administrator role is the only role that has the ability to create Tenant connections.

2. Go to the Tenant Setup page.

3. Click the Plus icon (+), then choose the hierarchy, typically, Customer.

4. Optionally, add a description. The tenant name auto-populates the Name field. You can update it if required.

5. At Cloud Environment Type, select the cloud environment type to authenticate to. For details, see Microsoft tenant cloud environment type.

6. At Solution, select solution capabilities to enable for this tenant.

   Note

   As at 25.3, the following solutions are available: UC Automation, Email

   Solutions must be enabled for your system in the Global Settings. See Solutions and the Microsoft tenant. Displayed fields on the form are filtered by selected solutions. For example:

   • Email enabled? Displays Email Configuration settings.
   • UC Automation and Email enabled? Displays Email Configuration settings. Use VOSS Central App Registration cannot be used (Relevant only when only a single solution is enabled).

   It is NOT possible to disable/remove a solution on the tenant once you've saved the tenant.

7. Configure settings and instructions based on enabled solutions:

   • Microsoft Application Authentication

     If you have only one solution enabled and want to use VOSS Central App Registration, select the checkbox, Then fill out the Tenant ID. The workflow applies the Application ID based on the selected solution.

     If you have more than one solution enabled you'll need to create your own app registration:

     • Application ID is auto-populated.
     • Fill out Tenant ID
     • UC Automation and Email solutions require a certificate. Select your certificate. The certificate is pushed to Windows during the Test Connection step after saving the tenant.
     • Certificate Thumbprint is auto-populated once you select the certificate.
     • Secret is required if you have an Arbitrator configured on Automate.

   • Data Sync Settings

     UC Automation and Email solutions

     Choose the sync to perform. Three options:

     • Create default data syncs: Creates default data syncs that ship with the product (these syncs are common to all solutions):
       • SyncMS365
       • SyncMS365Users
       • PurgeMS365
     • Create default data syncs with custom MS365 MIF: Creates a new model instance filter (MIF) for a specific model. Choose a filter or create a custom filter to run the default syncs with filtered data.
     • Use Datasync Builder: Uses the custom data sync template to create the data syncs based on selected solutions. You can either use a data sync profile or choose one or more templates to use with the Datasync Builder. Choosing individual templates will allow you to set the first execution date and time for any data sync template that requires schedules. Scheduling defined on the tenant in this way applies only to the tenant and is not added to a template or profile.

   • Email Configuration

     Email solution

     • Domain: Provide the Microsoft Exchange admin domain used to authenticate.

   Note

   • In Shared Central App Registration, VOSS builds and maintains the app registration in their Microsoft Entra ID tenant and performs organizational and application validation with Microsoft.
   • Tenant ID and Application ID are recorded in the app registration and identify the tenant in the Microsoft cloud.
   • For the certificate:
     • You can generate a certificate in Automate and upload it to MS Entra ID, or;
     • If you already have a signed certificate from another source in your organization and it's already uploaded to MS Entra ID, you can upload that certificate into Automate and have Automate manage it on itself.

8. Optionally, select Show Advanced Settings and Internet Proxy Settings to configure additional settings on the tenant, where relevant:

   Outbound Internet Proxy Settings:

   1. Do you have an outbound internet proxy deployed between the PowerShell proxy and the public internet?

      • Yes. Select Windows Server - Use HTTP Proxy.

        If the outbound Internet proxy requires authentication, select Windows Server - Use HTTP Proxy Authentication, and fill out a username and password.

        For the outbound Internet proxy IP address (FQDN) and port number, use the following format:

        xxx.xxx.xxx.xxx:yyyy (for example, 192.168.1.1:3128).

        If you wish to disable the use of a currently configured outbound internet proxy:

        • Uncheck Window Server - Use HTTP Proxy and save the Microsoft tenant configuration.

      • No. Clear the following fields: Windows Server - Use HTTP Proxy, Windows Server - Use HTTP Proxy Authentication, Windows Server - Proxy Server Username, Windows Server - Proxy Server Password

        Authenticated proxy is supported.

   2. At MS 365 HTTP proxy / MS 365 HTTPS proxy, set the outbound internet proxy server if required for traffic outbound to the public internet.

      The proxy setup defines the route for the MS Graph API communications that the system uses for communication with the MS 365 Cloud tenant.

      • For HTTP proxy traffic, fill out a MS 365 HTTP proxy value with the following format: http(s)://[user:password]@host:port/.

        Special characters in either the user or password must be URL encoded. Verify the required format with the proxy administrator.

      • For HTTPS proxy traffic, fill out a MS 365 HTTPS proxy value with the following format: http(s)://[user:password]@host:port/

        Special characters in either the user or password must be URL encoded. Verify the required format with the proxy administrator.

      Note

      • MS 365 HTTP proxy and MS 365 HTTPS proxy values will almost certainly be identical unless your proxy administrator has clearly told you that HTTP and HTTPS traffic are being proxied through different servers. It is not required that the MS 365 HTTP proxy address begin with http:// or that the MS 365 HTTPS proxy address begin with https://. It is perfectly acceptable to proxy HTTP traffic to an https:// address or HTTPS traffic to an http:// address.
      • In both cases the host can be a FQDN if resolvable via DNS or the IP address of the internet proxy.

   Advanced Settings

   The table describes fields in the Advanced Settings pane:

   Field	Description
   Maximum Rendered Template Size	The maximum allowed size of any rendered template for all models for all managed drivers. Size in bytes, so 900000000 is 900MB. Only set this value if the amount of data returned when using the default value is causing an error. Default is 900MB.
   MS Teams CsOnlineUser page size	Defines page size for the msteamsonline/CsOnlineUser device model. Only set this value if the amount of data returned when using the default value is causing an error.
   MS Teams Number page size	Defines the maximum number of records to retrieve at a time from APIs related to the msteamsonline/Number device model. Starting January 2025, Microsoft has set the page size limit for phone number retrieval to a maximum of 1000 numbers per query. Requests exceeding this limit will result in an error. See the Automate 24.2-PB1 release notes for the upgrade notes for EKB-22837, for details.
   MS 365 MsolUser page size	Defines the maximum number of records to retrieve at a time from the API related to device/msgraph/MSOLUser. For optimal performance, leave this field blank to use the default value, 999.
   MS 365 Group page size	Defines the maximum number of records to retrieve at a time from APIs related to device/msgraph/Group. For optimal performance, leave this field blank to use the default value, 999.
   Auto filter Teams users	Defines whether to add a default, automatic filter to all CsOnlineUser syncs to only return records matching MsolUsers in the cache. Default is False. When enabled (True), no other sync filters can be used for CsOnlineUser syncs. Using additional filters will trigger a system error in this case. Important Automate issues a warning when it detects an in condition for UserPrincipalName used alongside other CsOnlineUser filters during sync and filtering. In Microsoft tenants with auto-filter enabled, the expected records may not be returned if your MsolUser cache is not up to date.

   System Message: ERROR/3 (<string>, line 311)

   Content block expected for the "note" directive; none found.

   .. note::
   
   
   

For details on the auto filter for Teams users, see Microsoft syncs in the Best Practices Guide

9. Save the tenant configuration.

   Note

   Saving the tenant with the certificate deploys the certificate to the PowerShell proxy and installs it. You can then import the certificate on the tenant App registration in Microsoft Entra for authentication of all apps (MS Exchange, Teams, and Graph).

Next steps

• High level administrators with access to the data/MultivendorUsernameMappingMacros model instances should verify that no changes are needed in user name mapping macros prior to sync.

  Important

  For release 21.5-PB5, Multivendor environments using the data/MultivendorUsernameMappingMacros model at a hierarchy below sys level require an additional update. High level administrators with access to this model should ensure instances include:

  "username_macro_ms_365": [
     "{{ input.UserPrincipalName }}",
     "(( fn.is_none_or_empty input.username == fn.true ))<NOT_FOUND>(( data.User.username | username:input.username != '' ))<{{ data.User.username | username:input.username }}><NOT_FOUND>",
     "(( fn.is_none_or_empty input.username == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_365:input.username != '' ))<{{ data.User.username | username_ms_365:input.username }}><NOT_FOUND>",
     "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | email:input.UserPrincipalName != '' ))<{{ data.User.username | email:input.UserPrincipalName}}><NOT_FOUND>",
     "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_365:input.UserPrincipalName != '' ))<{{ data.User.username | username_ms_365:input.UserPrincipalName }}><NOT_FOUND>",
     "(( fn.is_none_or_empty previous.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_365:previous.UserPrincipalName != '' ))<{{ data.User.username | username_ms_365:previous.UserPrincipalName }}><NOT_FOUND>",
     "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_teams:input.UserPrincipalName != '' ))<{{ data.User.username | username_ms_teams:input.UserPrincipalName }}><NOT_FOUND>",
     "(( fn.is_none_or_empty previous.UserPrincipalName == fn.true ))<NOT_FOUND>(( data.User.username | username_ms_teams:previous.UserPrincipalName != '' ))<{{ data.User.username | username_ms_teams:previous.UserPrincipalName }}><NOT_FOUND>",
     "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( device.cucm.User.userid | userIdentity:input.UserPrincipalName != '' ))<{{ device.cucm.User.userid | userIdentity:input.UserPrincipalName }}><NOT_FOUND>",
     "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))<NOT_FOUND>(( device.cucm.User.userid | mailid:input.UserPrincipalName != '' ))<{{ device.cucm.User.userid | mailid:input.UserPrincipalName }}><NOT_FOUND>"
      ],
  

• Perform a sync from the Microsoft tenant:

  • Syncs import Microsoft users, tenant dial plan, licenses, and policies to the customer level.

    For Microsoft Exchange, ensure that instances for all four device models (User mailboxes, Shared Mailboxes, Room Mailboxes, and Distribution Mailboxes) are synced in at the level were the tenant exists.

  • If Security is enabled (Enable Defender for Endpoint set to True in Global Settings), a data collection and schedule is added.

    A Defender for Endpoint Data Collection <hierarchy name> schedule is created. This schedule can sync data according to this created collection and that allows for a batch sync of the device data. The collected data is then also available when Overbuild for Microsoft is run.

• Configure the customer-wide site defaults doc (SDD), CUSTOMER_TEMPLATE. See Site Defaults Doc templates.

• Add network device lists (NDLs) with Microsoft 365 and Microsoft Teams tenant details. NDLs are required when adding sites.

• Create sites.

Run the overbuild. See Overbuild for Microsoft in the UC Automation Guide

Configure Automate for Microsoft services in the UC Automation Guide

Related topics

Arbitrators in the Core Feature Guide

Shared central application registration in the UC Automation Guide

Generate a certificate for application registration in the UC Automation Guide

Upload a certificate to use for app registration in the UC Automation Guide

See PowerShell proxy server in the UC Automation Guide

Global Settings in the Core Guide

Datasync Builder in the Core Guide

Microsoft Defender setup, sync and overbuild in the UC Automation Guide

Overbuild for Microsoft in the UC Automation Guide

Network Device Lists (NDLs) in the Core Guide

Update a Microsoft tenant

Modifying a Microsoft tenant will only overwrite those driver parameters in the underlying connections (MSTeamsOnline, MSExchangeOnline, MSGraph) that are managed by the tenant workflows. Other driver parameters will be left as is.

It is NOT possible to disable/remove a solution on the tenant once you've saved the tenant.

Also refer to the Advanced Settings above to modify the page size options for the Microsoft Tenant in order to adjust the synchronization performance.

Related topics

Microsoft Quick Start Guide for Automate in the UC Automation Guide

Microsoft Overview in the UC Automation Guide

Microsoft syncs in the Best Practices Guide

Site Defaults Doc templates in the Core Guide

PowerShell proxy server in the UC Automation Guide

Overbuild for Microsoft in the UC Automation Guide

Microsoft tenant cloud environment type

When setting up the Microsoft tenant you can optionally choose a cloud environment type to authenticate to. Automate's default cloud environment for a Microsoft tenant is "Commercial".

On upgrade or install, the cloud environment type is set to this default value.

Automate also supports authentication to high security cloud environment types, allowing an admin to identify their Microsoft customer tenant as one that is operating in a high security cloud environment, either DoD (United States Department of Defense) or GCCH (Microsoft 365 Government Community Cloud High).

When the tenant cloud environment type is set to either DoD or GCCH, Automate sets the appropriate environment names for the Microsoft Teams and Microsoft Exchange PowerShell modules, and appropriate URLs are used for the Microsoft Graph API.

This relation implements the workflows to manage Microsoft Tenant connection parameters and enabled services.

Model Details: relation/MicrosoftTenant