Installing the HaloENGINE Service

This chapter details the necessary prerequisites for installing HaloENGINE Service.

Requirements

The following system requirements table specifies the minimum and recommended technical specifications, such as software and network resources, necessary to run HaloENGINE and HaloENGINE Service.

Requirements

Recommended URLs, Addresses, and Ports for MPIP

MIP SDK doesn't support the use of authenticated proxies. So, make sure you set the Microsoft 365 endpoints to bypass the proxy. View a list of endpoints at “Microsoft Online Documentation”. However, Microsoft recommends the following:

Recommended endpoints

Prerequisites

Before you install the HaloENGINE Service, there are a few things that you need.

Registering an Application in Microsoft Entra ID

This section will guide you through the steps of registering an application, obtaining the Client ID and Directory ID, and assigning permissions to the application.

Microsoft documentation

Any application to authenticate via Microsoft Entra ID must be registered in its directory. The information in the Microsoft documentation overrides any information published in this section. Please refer to Microsoft documentation for a comprehensive description.

For demonstration purposes, an application is created in the Azure portal; alternatively, you may create an application using https://entra.microsoft.com.

Prerequisite: You must have sufficient permissions to register an application with your Microsoft Entra ID tenant.

Create an Application

Follow the instructions below to register an application:

1. Sign in to the Microsoft Azure portal using an account with administrator permission.

2. On the portal's Home page, under Azure services, or on the left side of the navigation pane, choose Microsoft Entra ID.

   

   Selecting Microsoft Entra ID

3. On the Overview page, in the left navigation pane, click App registrations.

4. On the App registrations page, select New registration or Register an Application (this button appears only if no applications have already been created).

   

   New application registration

5. On the Register an application page, enter your application's registration information.

   

   Webapp application details

6. In the Name section, enter a meaningful application name.

7. Under Supported account types, select the option Accounts in this organizational directory only (single tenant). As of now, the HaloENGINE Service only supports a single tenant.

8. Under Redirect URI: Select Web, and then type a valid redirect URI for your application. For example, https://localhost.

9. When finished, click Register.

10. An overview page for the new application registration is created and displayed.

    

    Application ID and Tenant ID

11. The following values are shown on the portal once registration is complete. To copy and save the ID value in a text editor, hover your cursor over it and click the Copy to clipboard icon.

    1. Application ID – It is also referred to as Client ID.

    2. Directory ID – It is also referred to as Tenant ID.

Save the authentication parameters

In a text editor (such as Notepad), copy the value of Application (client) ID and Directory (tenant) ID, and save it for initializing the HaloENGINE Service.

Add Required Permissions 

To protect content with MIP SDK, you must provide the necessary API permissions to the application created in the previous section.

1. In the sidebar of the application page, select API permissions. The API permissions page for the new application registration page appears.

2. Click Add a permission button. The Request API permissions page appears.

3. Under the Select an API setting, select APIs my organization uses. A list appears containing the applications in your directory that expose APIs.

4. In the search box, type in the name of the permission indicated in the "Required Permissions" table below. Alternatively, you could scroll to find the API.

5. For example, type Microsoft Information Protection Sync Service into the search box. The following figure shows how the API is listed:

   

   API selection

6. Now, click on the displayed API. You can see two permissions on the page − Delegated permissions and Application permissions.

7. Click Application permissions button and then under the Permission section, select the check box against "Read all unified policies of the tenant." 

   

   Adding permission

8. Click Add permissions.

9. Repeat the steps outlined above to add the other required permissions listed in the “Required permissions” table below.

10. You will be taken back to the API permissions page, where the permissions have been saved and added to the table with the status "Not granted."

    

    Required API Permissions

11. Click Grant admin consent for your company button. You will be prompted to accept the consent confirmation; click Yes to the question.

12. After accepting the admin consent, the Status will change to "Granted."

    

    API Permissions with admin consent

13. The following table lists the required permissions.

Required permissions #1

Additional Permission (Only for Decryption)

The above-mentioned permissions are adequate for applying the MPIP label to a file with the owner as SPN (Service Principal Name) ID or any user email ID. Additionally, the HaloENGINE Service requires the below-mentioned superuser privilege for the decryption function when the owner is not as SPN.

Required permissions #2

Upload the Certificate in Azure Portal 

HaloENGINE Service is based on certificate authentication, so you must enter your certificate information into the registered application.

Prerequisites: 

1. Certificate: 

   1. Make sure to have a valid certificate that contains keys such as -KeyExportPolicy Exportable and -KeySpec Signature.

   2. And that can also be a self-signed certificate. Note: As a best practice and for security reasons, we recommend using a self-signed certificate in a test environment and NOT recommended for a production environment.

2. Install the certificate:

   1. Make sure to install this certificate on a Windows Server machine where the HaloENGINE Service is going to be installed.

   2. Certificate Store can either be Current User or Local Computer. 

   3. If it is a self-signed certificate, then it should also be installed in “Trusted Root Certification Authorities”. 

   4. If the certificate is signed, then the root CA authority and intermediate CA authority (if any) should also be installed in the respective trusted store.

To upload the public key of certificate, follow the below steps: 

1. In the sidebar of the new application page, select Certificate & secrets. 

2. Under the Certificate section, click Upload certificate. The Upload certificate dialog appears as shown in the below figure:

   

   Upload certificate #1

3. Click on the icon folder icon to select the certificate and click Open. For illustration purposes, the file DESKTOP001.cer is used.

4. Now, click Add. The certificate will get uploaded and its thumbprint will be displayed on the page as shown in the below figure:

   

   Upload certificate #2

5. You are now ready to install the HaloENGINE Service.

Create and Configure the Sensitivity Labels

As an administrator, you can create, configure, and publish sensitivity labels for various levels of content sensitivity based on your organization's classification taxonomy. Use names or terms that are familiar to your users. Consider starting with label names like Personal, Public, General, Confidential, and Highly Confidential if you don't already have a taxonomy in place. For more details, please refer to Microsoft online documentation.

Others

Before you begin, make sure that the following prerequisites are met in your system:

1. In case of silent installation, make sure to install Visual Studio Redistributable latest VS2015-2022 from the following link: https://aka.ms/vs/17/release/vc_redist.x64.exe (x64 version).

2. Make sure the user who is running the service or a specific group that the user belongs to is not to the Deny log on as a service policy (Local Security Policy > Security Settings > Local Policies > User Rights Assignment). If the user(s) exist, the Error 1069: The Service did not start due to a logon failure message will appear while running the HaloENGINE Service.