.. _ms-tenant-setup: Microsoft tenant setup ------------------------- .. _21.2|VOSS-873: .. _21.3|VOSS-891: .. _21.3|EKB-10448: .. _21.3-PB2|EKB-13056: .. _21.4-PB4|EKB-17924: .. _24.1|EKB-19607: .. _24.1|VOSS-1368: .. _24.1|VOSS-1265: .. _24.1-PB2|EKB-21650: .. _24.2-PB1|EKB-21770: .. _24.2-PB1|EKB-22837: .. _25.1|EKB-21976: .. _25.3|VOSS-1507: .. _25.3|EKB-22640: .. _25.3|VOSS-1545: .. _25.3|VOSS-1560: .. _25.4|VOSS-1470: .. _25.4|EKB-28390: .. tip:: :ref:`use-action-search-to-navigate-automate` Overview ................. :bdg-primary:`Microsoft` :bdg-secondary:`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-for-the-ms-tenant: Solutions and the Microsoft tenant ................................... Solutions are licensed system components delivering specific functionality and features. These solutions are enabled in the Global Settings (**Enabled Solutions** and **Enabled Services**). The following solutions are enabled by default: * UC Automation * Email 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 .. rubric:: Removing a solution from a Microsoft tenant You can remove a solution from a Microsoft tenant after the tenant is created. When removing a solution from the Microsoft tenant: * Associated data syncs, data collections, schedules, and connection parameters are removed if they are no longer used by any other solution * Shared resources are retained if still required * Cleanup is handled via workflows (no manual cleanup required) 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 VOSS and the PowerShell Proxy * Between the PowerShell Proxy and the Microsoft tenant * The Graph API connection between VOSS and the Microsoft tenant .. image:: /src/images/ms-tenant-app-reg.png .. rubric:: 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 :ref:`solutions-for-the-ms-tenant`. A secret or certificate created when registering VOSS as an application object with Microsoft Entra ID. For greater security, certificate is preferred. If an Arbitrator is configured on VOSS, secret is required. .. raw:: latex See *Arbitrators* in the Core Guide .. raw:: html See Arbitrators .. rubric:: 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. #. Optionally, add a description. The tenant name auto-populates the **Name** field. You can update it if required. #. At **Cloud Environment Type**, select the cloud environment type to authenticate to. For details, see :ref:`ms-tenant-cloud-environment-type`. #. At **Solution**, select solution capabilities to enable for this tenant. .. note:: The following solutions are enabled by default: *UC Automation*, *Email* Solutions must be enabled for your system in the Global Settings. See :ref:`solutions-for-the-ms-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). Solutions can be removed after tenant creation. When a solution is removed, VOSS performs controlled cleanup of associated resources. #. 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 VOSS. * **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 VOSS 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 VOSS and have VOSS 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**: a. **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. b. 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: .. tabularcolumns:: |p{5cm}|p{10cm}| +---------------------------------+-----------------------------------------------------------------------+ | 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:: | | | | | | VOSS 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. | +---------------------------------+-----------------------------------------------------------------------+ .. note:: .. raw:: latex For details on the auto filter for Teams users, see Microsoft syncs in the Best Practices Guide .. raw:: html For details on the auto filter for Teams users, see Microsoft syncs 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). .. rubric:: 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 ))(( data.User.username | username:input.username != '' ))<{{ data.User.username | username:input.username }}>", "(( fn.is_none_or_empty input.username == fn.true ))(( data.User.username | username_ms_365:input.username != '' ))<{{ data.User.username | username_ms_365:input.username }}>", "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))(( data.User.username | email:input.UserPrincipalName != '' ))<{{ data.User.username | email:input.UserPrincipalName}}>", "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))(( data.User.username | username_ms_365:input.UserPrincipalName != '' ))<{{ data.User.username | username_ms_365:input.UserPrincipalName }}>", "(( fn.is_none_or_empty previous.UserPrincipalName == fn.true ))(( data.User.username | username_ms_365:previous.UserPrincipalName != '' ))<{{ data.User.username | username_ms_365:previous.UserPrincipalName }}>", "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))(( data.User.username | username_ms_teams:input.UserPrincipalName != '' ))<{{ data.User.username | username_ms_teams:input.UserPrincipalName }}>", "(( fn.is_none_or_empty previous.UserPrincipalName == fn.true ))(( data.User.username | username_ms_teams:previous.UserPrincipalName != '' ))<{{ data.User.username | username_ms_teams:previous.UserPrincipalName }}>", "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))(( device.cucm.User.userid | userIdentity:input.UserPrincipalName != '' ))<{{ device.cucm.User.userid | userIdentity:input.UserPrincipalName }}>", "(( fn.is_none_or_empty input.UserPrincipalName == fn.true ))(( device.cucm.User.userid | mailid:input.UserPrincipalName != '' ))<{{ device.cucm.User.userid | mailid:input.UserPrincipalName }}>" ], * 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 ** 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. * .. raw:: latex Run the overbuild. See Overbuild for Microsoft in the UC Automation Guide .. raw:: html Run the Overbuild for Microsoft * .. raw:: latex Configure VOSS for Microsoft services in the UC Automation Guide .. raw:: html Configure VOSS for Microsoft services .. rubric:: Related topics * .. raw:: latex Arbitrators in the Core Feature Guide .. raw:: html Arbitrators * .. raw:: latex Shared central application registration in the UC Automation Guide .. raw:: html Shared central application registration * .. raw:: latex Generate a certificate for application registration in the UC Automation Guide .. raw:: html Generate a certificate for application registration * .. raw:: latex Upload a certificate to use for app registration in the UC Automation Guide .. raw:: html Upload a certificate to use for app registration * .. raw:: latex See PowerShell proxy server in the UC Automation Guide .. raw:: html PowerShell proxy server * .. raw:: latex Global Settings in the Core Guide .. raw:: html Global Settings * .. raw:: latex Datasync Builder in the Core Guide .. raw:: html Datasync Builder * .. raw:: latex Microsoft Defender setup, sync and overbuild in the UC Automation Guide .. raw:: html Microsoft Defender setup, sync and overbuild * .. raw:: latex Overbuild for Microsoft in the UC Automation Guide .. raw:: html Overbuild for Microsoft * .. raw:: latex Network Device Lists (NDLs) in the Core Guide .. raw:: html Network Device Lists (NDLs) 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. Solutions can be removed after tenant creation. When a solution is removed, VOSS performs controlled cleanup of associated resources. When modifying a tenant to add or remove solutions, that workflows that execute ensure that: * New components are added if solution evolves * Existing resources are validated Also refer to the **Advanced Settings** above to modify the *page size* options for the Microsoft Tenant in order to adjust the synchronization performance. .. rubric:: Related topics * .. raw:: latex Microsoft Quick Start Guide for VOSS in the UC Automation Guide .. raw:: html Microsoft Quick Start Guide for VOSS * .. raw:: latex Microsoft Overview in the UC Automation Guide .. raw:: html Microsoft Overview * .. raw:: latex Microsoft syncs in the Best Practices Guide .. raw:: html Microsoft syncs * .. raw:: latex Site Defaults Doc templates in the Core Guide .. raw:: html Site Defaults Doc templates * .. raw:: latex PowerShell proxy server in the UC Automation Guide .. raw:: html PowerShell proxy server * .. raw:: latex Overbuild for Microsoft in the UC Automation Guide .. raw:: html Overbuild for Microsoft .. _ms-tenant-cloud-environment-type: Microsoft tenant cloud environment type ......................................... When setting up the Microsoft tenant you can optionally choose a cloud environment type to authenticate to. VOSS's default cloud environment for a Microsoft tenant is "Commercial". On upgrade or install, the cloud environment type is set to this default value. VOSS 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, VOSS sets the appropriate environment names for the Microsoft Teams and Microsoft Exchange PowerShell modules, and appropriate URLs are used for the Microsoft Graph API.