.. _ms-configuration-setup:

Microsoft Configuration Setup
------------------------------

.. _21.1|VOSS-847:

VOSS-4-UC provides management and administration for Microsoft 365 and
Microsoft Team's cloud assets. This document outlines the required
authentication steps needed to configure a connection between a Microsoft
365 and Teams Tenant and VOSS-4-UC.

You will need to be a Global Administrator of the Microsoft 365 and
Teams Tenant to complete the following steps:


Step 1: Register An Application Object (Access to Microsoft Azure AD)
.....................................................................

The application objects describe the VOSS-4-UC application to Azure AD and
can be considered the definition of the VOSS-4-UC application, allowing
the Azure AD service to know how to issue tokens to the VOSS-4-UC
application based on its settings.

To register your application and add the app's registration information
to your solution, follow these steps:

.. note::

   If you have access to multiple tenants, use the Directory +
   subscription filter in the top menu to select the tenant in which you
   want to register an application.

#. Sign in to the Azure portal (``portal.azure.com``)
   using your administrator credentials.

   .. important::

      Manage the Security defaults for the tenant as follows:

      * Set **Access management for Azure resources** to **No**.

        .. image:: /src/images/ms-config-manage-security-defaults.png

      * Set **Enable Security defaults** to **No**.

        .. image:: /src/images/ms-config-enable-security.png

      These settings are required since API access does not cater for 2-step authentication

#. Search for and select **Azure Active Directory**.
#. Under **Manage**, select **App registrations > New registration**.

   .. image:: /src/images/ms-config-new-reg.png

#. Enter a Name for your application, for example ``VOSS4UC``. Users of your
   application might see this name, and you can change it later.
#. Select **Accounts in this organization only**
#. Ignore the **Redirect URI** section
#. Select **Register**.
#. Under **Manage**, select **Certificates & secrets**.

   .. image:: /src/images/ms-config-cert-secrets.png

#. Under **Client secrets**, select **New client secret**, enter a name, and
   then select **Add**. The add actions opens the **Add a client secret**
   pane. Record the secret value in a safe location for use in a later
   step. The secret is used in the MS Connection configuration in VOSS-4-UC.

   .. important::

      The secret value is *only* available when the secret is created and not later.
      If the value is not copied on time, a new secret will be required.

   .. image:: /src/images/ms-config-client-secret.png

#. Under **Manage**, select **API Permissions > Add a permission**. Select
   **Microsoft Graph**.

   .. image:: /src/images/ms-config-ms-graph-permissions.png

#. Select **Application permissions**.
#. Select **Grant Admin Consent** to allow ``User.Read.All``
#. Under **User node**, select:

   * ``User.Read.All``
   * ``Directory.Read.All``

#. Select **Add permissions**


Step 2: Create a Service Account (Access to Microsoft Teams)
.............................................................

#. Sign in to the Azure portal (``portal.azure.com``)
#. On the Admin home page, go to **Users > Active users** and  click on
   button **Add a user**
#. Enter a **Display Name**
#. Enter a **User Name**
#. Ensure that the domain is the ``company.onmicrosoft.com`` one
#. Select **Let me create a password** and enter a strong one
#. Ensure **Require this user to change their password when they first sign in**
   is *not* ticked
#. Once the user is created, assign the **Global Administrator**
   role from the **Assigned Roles** menu option.

.. important::

   Take note of the Username and Password - it will be needed to configure
   the VOSS-4-UC connection.


Step 3: Configure the MS Connection in V4UC
............................................


The Microsoft 365 information required to set up a MS Tenant app in VOSS-4-UC
is found as follows:

.. tabularcolumns:: |p{3cm}|p{12cm}|

+-----------+-----------------------------------------------------+
| Field     | Source                                              |
+===========+=====================================================+
| Client ID | **Overview > Essentials > Application (client) ID** |
+-----------+-----------------------------------------------------+
| Tenant ID | **Overview > Essentials > Directory (tenant) ID**   |
+-----------+-----------------------------------------------------+
| Secret    | The secret value is shown during the                |
|           | app registration only once, and                     |
|           | should be recorded at that point.                   |
+-----------+-----------------------------------------------------+


.. image:: /src/images/MS365-info.png

Use this information to set up a MS Tenant app in VOSS-4-UC.
For steps to do this, see: :ref:`tasks-configure-ms-tenant`