Prerequisites

This chapter describes the prerequisites that must be completed before installing and configuring HaloENGINE. These steps ensure that the product integrates smoothly with your organization’s security and compliance infrastructure. The following setup tasks are required:

1. Registering an application in Microsoft Entra ID

2. Creating and configuring Sensitivity Labels

3. HaloENGINE Tomcat Service Runtime Conditions

4. Obtaining the HaloENGINE License

5. Configuring User Management Settings in the Azure portal

6. Setting up Microsoft Sentinel

Completing these prerequisites in advance helps streamline the deployment process and ensures that HaloENGINE functions as intended within your environment.

Registering an Application in Microsoft Entra ID

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

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

Create an Application

Follow these steps to register the application:

1. Log in to the Microsoft Entra admin center using an account that has administrator privileges.

2. If you have access to multiple tenants, click the Settings icon in the top menu and select the tenant for which you want to register the application from the Directories + subscriptions menu.

3. You will be directed to the homepage.

   

   Selecting Microsoft Entra ID

4. Click Identity > Applications > App registrations on the left of the navigation pane.

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

   

   New application registration

6. On the Register an application page, enter the registration details for your application.

   

   Application details

   1. In the Name field, enter an appropriate application name.

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

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

   4. When finished, click Register.

7. The home page of the new application is created and displayed.

   

   Application ID and Tenant ID

8. 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.

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 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 near "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 permissions mentioned above 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 Tomcat Service requires the following superuser privilege for the decryption function when the owner is not as SPN.

Required permissions #2

Upload the Certificate in the Azure Portal 

The HaloENGINE Tomcat Service relies on certificate-based authentication to access MPIP services. Therefore, you must enter your certificate information in the registered application before proceeding with the configuration.

Prerequisites: 

1. Certificate: 

   1. Ensure that you have a valid certificate containing the following key properties: -KeyExportPolicy Exportable and -KeySpec Signature.

   2. The certificate can also be self-signed. Note: As a best practice and for security reasons, use a self-signed certificate only in a test environment. It is not recommended for production environments.

2. Local Computer certificate store: The certificate required for MPIP authentication must be installed in the Local Computer certificate store, along with the Root CA and Intermediate CA certificates.

   1. If the certificate is CA-signed, install all related certificates in their respective stores (Root, Intermediate, and Personal).

   2. If the certificate is self-signed, install it in both the Trusted Root Certification Authorities and Personal stores of the Local Computer.

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

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 figure below:

   

   Upload certificate #1

3. Click on the 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 figure below:

   

   Upload certificate #2

Creating and configuring 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.

Conditions for Running the HaloENGINE Tomcat Service

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

Deny log on as a service policy

If the service is running under a specific user or a specific group, ensure that the user is not restricted by 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 appears while running the HaloENGINE Tomcat service.

Allow non-admin users to access a private key (without full admin rights)

During installation, the HaloENGINE gets the required Azure tenant details and certificate thumbprint. When the HaloENGINE Tomcat service starts, it tries to connect to the MPIP services using the details entered during installation. As part of this process, it validates the certificate thumbprint against the certificate installed in the Local Computer certificate store. The thumbprint entered in the installation wizard must match the one available in the Local Computer certificate store.

If the service runs under a non-administrative user account, the user may not have sufficient permissions to access the certificate’s private keys when the certificate is installed in the Local Computer store. This restriction prevents successful authentication with MPIP services. To resolve this issue, grant the user Read permission to access the certificate’s private key by following the steps listed below.

Any errors encountered during this process are recorded in the log file. If the verification succeeds, the service proceeds with initialization.

Prerequisites

1. The required certificates (machine certificate, root CA, and intermediate CA) are already installed.

2. The private key is stored in the Windows Certificate Store under Local Computer.

3. You have administrative rights to perform the setup.

Follow the procedure below to grant read access:

1. Open Certificate Manager as Administrator.

2. Press Win + R, type mmc, and press Enter.

3. In the console, go to File and select Add/Remove Snap-in.

4. Select Certificates from the list and click Add.

5. Choose the Computer account, then click Next, followed by Finish, and then OK.

6. In the left panel, expand Certificates (Local Computer), expand Personal, and select Certificates.

7. Identify the certificate that contains the private key.

8. Right-click the certificate, select All Tasks, and then select Manage Private Keys.

9. In the Permissions window, click Add and enter the non-admin username (for example, TESTIL) and click OK.

10. Select the Read permission, click Apply, and then click OK.

    

    Granting private key access to a non-admin user

Obtaining the HaloENGINE License 

Before installing the HaloENGINE, we recommend obtaining the license file (license.lic) from Secude support to enable the HaloENGINE functionalities. The license file you received from Secude will include specific features and system types. This implies that only the system types specified in the license are accessible via their respective endpoints. After configuring the admin portal, import the license as instructed in the section " Phase 2. Activate License ".

The following picture illustrates how the client communicates with the HaloENGINE.

System types and protocol

The table below will assist you in deciding the type of license you should obtain from Secude.

Obtaining license

User Management Settings

Make a default (also known as regular) administrator account after installing the HaloENGINE component. This account is referred to as "Super Admin," and it has greater access than a typical administrator account. This account has full access to your HaloENGINE component.

User Accounts

User Accounts

Settings in Azure Portal

User management is often included with Microsoft Azure and involves several request exchanges between the HaloENGINE Admin Portal and the identity provider, Microsoft Entra ID.

In the Azure portal, follow the steps below to configure user authentication and authorization settings.

Step 1: Create a New Web Application

1. You can either leverage an existing Web (Redirect URI) application or create a new one in Azure Portal. To serve as an example, the Web application User Management is created.

2. When registration is complete, the Overview page displays the Application ID and Tenant ID values. These values uniquely identify your application on the Microsoft identity platform. To preserve the values, copy them to the clipboard and paste them into a text editor (such as Notepad).

Step 2: Authentication Settings

1. In the left navigation pane, select Authentication.

   

   Authentication settings

2. Under the Web section, click Add URI and enter the following reply URLs one by one:

   1. https://login.azure.net/authResponse

   2. HaloENGINE Admin portal URL:

      • https://<ip>:<port>/haloengine-admin/login/oauth2/code/<tenant name> (for example, https://10.91.0.65:8746/haloengine-admin/login/oauth2/code/halosecude)

      • Or http://<localhost>:<port>/haloengine-admin/login/oauth2/code/<tenant name> (for example, http://localhost:8383/haloengine-admin/login/oauth2/code/halosecude)

3. Under Front-channel logout URL section, enter the URL − https://login.azure.net/logout.

4. Under the Implicit grant and hybrid flows section, select Access tokens, and ID tokens checkboxes.

5. Click Save.

Step 3: Certificates & Secrets

1. In the left navigation pane, click Certificates & secrets.

2. Under Client secrets, click + New client secret.

3. On the Add a client secret page, enter a Description, choose the validity period under Expires, and click Add.

4. After clicking Add, a new row appears under Client secrets.

   

   Client secret value

5. Copy the Value field immediately, as it will only be displayed once.

6. Store this value securely and use it for Tenant Configuration .

Step 4: Token Settings

1. In the left navigation pane, select Token configuration and click Add groups claim.

   

   Token Settings

2. Select the following options:

   1. Security groups

   2. Directory roles

   3. All groups

3. Click Save.

Step 5: Expose API

1. In the left navigation pane, select Expose an API.

   

   Adding scope#1

2. Click Add a scope and enter the scope following api:// in Application ID URI. In this example, api://halocoreadmin is used. 

3. Click Save and Continue.

4. Again, click Add a scope and enter the following values:

   

   Adding scope #2

   1. Scope name: enter Config.ReadWrites

   2. Who can consent?: select Admins and users 

   3. Admin consent display name: enter HalocoreAdminConsent

   4. Admin consent description: enter Halocore Read and Write

   5. State: select Enabled

5. Click Add scope. You can see the scope displayed in the UI.

6. Copy the generated scope api://halocoreadmin/Config.ReadWrites to the clipboard and save it in a text editor (such as Notepad).

Step 6: Create Roles

1. In the left navigation pane, select APP roles.

2. Click Create app role and enter the following values:

   1. Display name: ROLE_CUSTOMER_ADMIN

   2. Allowed member types: select Users/Groups 

   3. Value: ROLE_CUSTOMER_ADMIN

   4. Description: CUSTOMER_ADMIN

   5. Do you want to enable this app role? – Select this option.

   6. Repeat the above steps for the role ROLE_CUSTOMER_USER.

      

      Adding Roles

3. Click Apply.

4. The roles are added to the list.

   

   Create Roles

Step 7: Apply Role to Users

1. In the Microsoft Entra ID pane, select Enterprise applications. 

   1. The Enterprise Applications page will appear with a list of existing Service Principals in your tenant.

   2. In the search box, enter your application name. In this example, User Management is entered in the search box.

      

      Apply role to user #1

   3. The search result will be displayed. 

   4. Now, click on the link from the list. The Overview page of the application will appear:

      

      Apply role to user #2

   5. Click Assign users and groups. The Users and groups page will appear.

   6. On the Users and groups page, click Add user/group. The Add Assignment page will appear.

   7. Under Users and groups:

      • Click None Selected and search for a user (for example, John).

      • Click Select and Assign.

        

        Adding users

   8. Under Select a role:

      • Click None Selected and search for the role ROLE_CUSTOMER_ADMIN.

      • Click Select and Assign.

        

        Apply role to user #3

   9. Repeat the above steps for the role ROLE_CUSTOMER_USER (for example, user Derek is assigned to this role).

2. Related tasks: After the initial configuration of the HaloENGINE Admin Portal, you need to use the above values to configure tenant details. Please refer to the section " Phase 7. Tenant Configuration ".

Forwarding Logs to Microsoft Sentinel

Microsoft Sentinel is a scalable, cloud-native security information and event management (SIEM) that delivers an intelligent and comprehensive solution for SIEM. Microsoft Sentinel provides cyberthreat detection, investigation, response, and proactive hunting, with a bird's-eye view across your enterprise. To begin using Microsoft Sentinel, the log analytics workspace must be configured.

Configuring Microsoft Sentinel

The explanation given in this section is only meant to serve as an example. Only the fundamental procedures for creating a workspace are shown in this section. Please refer to the Microsoft documentation for a detailed explanation of the configuration and settings. The information in the Microsoft documentation overrides any information published in this section.

Prerequisite: Ensure that you have permission to perform this procedure.

1. Log in to the Microsoft Azure portal.

2. In the search bar, type Microsoft Sentinel. As you start typing, the list filters according to your input.

3. Select Microsoft Sentinel from the search results.

4. The Microsoft Sentinel page will appear. Here, you need to click Create at the top of the page.

5. On the Add Microsoft Sentinel to a workspace page, click Create a new workspace.

6. The Create Log Analytics Workspace page will appear as shown below, and you must enter the required details on this page.

   

   Workspace #1

7. Select a resource group from the list.

   1. Provide a name for your workspace.

   2. Choose a region from the list.

8. Once that is done, you can leave other options as-is, and then click on Review + Create and finally click on Create after the validation.

   

   Workspace #2

9. The new workspace will be listed as follows:

   

   Workspace #3

10. Select the new workspace and click Add. The Add button will only be enabled if you have the required permission.

11. The connection between Microsoft Sentinel and Log Analytics is successfully created.

Fetching Key Details from Log Analytics Workspace

This section describes how to obtain the Log Analytics agent keys. Log Analytics agent keys are required to transfer logs from the HaloENGINE Admin portal to Microsoft Sentinel.

1. On the search bar, type Log Analytics workspace. As you start typing, the list filters according to your input.

2. Select Log Analytics workspace from the search results.

3. The Log Analytics workspace page now includes the new workspace you created in the previous section.

4. Select the new workspace.

5. In the menu, select Settings > Agents.

6. The page will provide the necessary information, including the Workspace ID and Primary Key.

   

   Workspace #4

7. In a text editor (such as Notepad), copy the value of the Workspace ID and Primary key and save it for configuring the “ Sentinel Log ” in the HaloENGINE Admin portal.