Prerequisites

This chapter describes the prerequisites that must be completed before installing and configuring HaloENGINE GenNXT. Completing these tasks ensures that HaloENGINE GenNXT integrates correctly with your organization's Microsoft Purview Information Protection environment and security infrastructure. The following setup tasks are required:

1. Register an application in Microsoft Entra ID

2. Configure Microsoft Purview Information Protection prerequisites

   1. Create and configure sensitivity labels

   2. Configure the required MPIP endpoints and network ports

   3. Enable TLS 1.2 support on the client workstation for Microsoft Entra ID

3. Configure User Management Settings in Microsoft Entra ID

4. Verify the HaloENGINE GenNXT Tomcat Service runtime requirements

5. Obtain the HaloENGINE GenNXT license

6. Configure MPIP authentication

7. Tomcat HTTPS Configuration

Complete these prerequisites before starting the installation to ensure a smooth deployment and reliable HaloENGINE GenNXT operation.

Register an Application in Microsoft Entra ID

This section describes how to register an application in Microsoft Entra ID, obtain the Application (client) ID and Directory (tenant) ID, assign the required API permissions, and upload the certificate required for MPIP authentication.

Prerequisite: You must have sufficient administrative privileges to register an application in 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. From Directories + subscriptions, select the tenant in which you want to register the application.

3. The application homepage opens.

   

   Selecting Microsoft Entra ID

4. In the left navigation pane, select Entra ID > App registrations.

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

   

   New application registration

6. On the Register an application page, configure the following:

   

   Application details

   1. Name: Enter an appropriate name for the application.

   2. Supported account types: Select Single tenant only from the list. HaloENGINE GenNXT currently supports only single-tenant applications.

   3. Redirect URI: Select Web and enter a valid redirect URI. For example, https://localhost.

7. Click Register.

8. The Overview page of the newly registered application opens.

   

   Application ID and Tenant ID

9. Once registration is complete, the portal displays the following values. 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 using the MIP SDK, you must provide the necessary API permissions to the application created in the previous section.

1. In the left navigation pane of the application, select API permissions.

2. Click Add a permission. 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, enter the name of the API listed in the Required API Permissions table. 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. Select the displayed API. The page displays two permission types: Delegated permissions and Application permissions.

7. Click Application permissions and then, under the Permission section, select the checkbox 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. The API permissions page opens, and the added permissions appear in the table with the status Not granted.

    

    Required API Permissions

11. Click Grant admin consent for your company. When prompted, click Yes to confirm the consent request.

12. After the admin consent is accepted, the status changes 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 GenNXT Tomcat Service requires the following superuser privilege for the decryption function when the owner is not as SPN.

Required permissions #2

Upload the Certificate

The HaloENGINE GenNXT Tomcat Service uses certificate-based authentication to access MPIP services. Therefore, you must upload the certificate to 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. As a best practice, use a self-signed certificate only in a test environment.

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 certificate, follow these steps:

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

2. Under Certificates, click Upload certificate. The Upload certificate dialog box opens.

   

   Upload certificate #1

3. Click the folder icon, select the certificate, and click Open. For example, the file DESKTOP001.cer is used.

4. Click Add. The certificate is uploaded, and its thumbprint appears on the page.

   

   Upload certificate #2

Office 365 Subscription Details

1. Microsoft Purview Information Protection must be fully configured.

2. An Office 365 subscription is required to use Azure RMS and MPIP functionality.

3. A working Microsoft Entra ID service must be available.

4. Transport Layer Security (TLS) 1.2 or higher must be enabled to ensure the use of cryptographically secure protocols at all client workstations. For more information, refer to the section “Enable Support for TLS 1.2 at the Client Workstation for Microsoft Entra ID”.

5. Monitor logging: Your subscription must include Log Analytics on the same tenant as Microsoft Entra ID.

Create and Configure 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 information, refer to the Microsoft online documentation.

Recommended URLs, Addresses, and Ports for MPIP

MIP SDK does not support the use of authenticated proxies. Therefore, ensure that you set the Microsoft 365 endpoints to bypass the proxy. For a list of endpoints, refer to the Microsoft documentation “Microsoft Online Documentation”. The following endpoints are recommended:

Recommended endpoints

Sovereign cloud: For Microsoft 365 U.S. Government GCC High and DoD environments, configure the required Microsoft service endpoints. For endpoint details, see Microsoft 365 U.S. Government GCC High endpoints.

Enable TLS 1.2 for Microsoft Entra ID Authentication

To improve tenant security and comply with industry standards, Microsoft Entra ID stopped supporting the following Transport Layer Security (TLS) protocols and ciphers:

1. TLS 1.1

2. TLS 1.0

3. 3DES cipher suite (TLS_RSA_WITH_3DES_EDE_CBC_SHA)

To authenticate with Microsoft Entra ID, TLS 1.2 must be enabled on the client workstation. For instructions, refer to the Microsoft documentation on enabling TLS 1.2 in the following link: Microsoft article to enable TLS 1.2.

Complete the following steps:

1. Update the Windows Operating System

2. Update .NET Framework

3. Set the following registry settings:

Registry entries

Configure Microsoft Entra ID for User Management

During the first sign-in to the HaloENGINE GenNXT Admin Portal, a default administrator account with Super Admin privileges is created. The Super Admin account has full administrative privileges and unrestricted access to the HaloENGINE GenNXT Admin Portal.

You can configure additional user accounts by creating application roles and assigning them to users based on their business responsibilities in Microsoft Entra ID. The following user roles are available:

• Customer_Admin

  • Role: ROLE_CUSTOMER_ADMIN

  • User validation: Microsoft Entra authentication

• Customer_User

  • Role: ROLE_CUSTOMER_USER

  • User validation: Microsoft Entra authentication

Complete the following steps in the Microsoft Entra admin center to configure user authentication and authorization for the HaloENGINE GenNXT Admin Portal.

Step 1: Create a New Web Application

1. You can use the web application created in the previous section or create a new application in the Microsoft Entra admin center. For this example, a new web application named User Management is created.

2. When registration is complete, the Overview page displays the Application ID (Client ID) and Directory ID (Tenant ID). Copy these values and save them in a text editor, such as Notepad, for later use.

   

   Client ID and Tenant ID

Step 2: Authentication Settings

1. In the left navigation pane, select Authentication.

2. Under Redirect URI Configuration tab, click Add Redirect URI.

3. On the Select a platform to add redirect URI page, under Web applications, select Web. Enter the following redirect URIs:

• • https://<ip>:<port>/haloengine-admin/login/oauth2/code/<tenant name>

  • https://<ip>:<port>/haloengine-admin/azure/callback

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

  • Click Configure.

1. • 

     Redirect URI

2. Go to the Settings tab.

   • Under Front-channel logout URL, enter the following URL: https://login.azure.net/logout

   • Under Implicit grant and hybrid flows, select the following check boxes: Access tokens (used for implicit flows) and ID tokens (used for implicit and hybrid flows).

     

     Front-channel logout URL

3. Click Save.

Step 3: Certificates & Secrets

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

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

3. On the Add a client secret page, enter a description, select an expiration period under Expires, and then click Add.

4. After you click Add, the new client secret appears under Client secrets.

   

   Client secret

5. Copy the Value immediately. It is displayed only once.

6. Store the client secret securely. You will need it when configuring the tenant in the Admin Portal.

Step 4: Token Settings

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

   

   Token configuration

2. Select the following group types:

   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.

2. Click Add a scope.

3. In the Application ID URI field, enter the application ID URI. In this example, api://halocoreadmin is used.

   

   Application ID URI

4. Click Save and continue.

5. Click Add a scope again, and then enter the following values:

   

   Add a scope

   • Scope name: Config.ReadWrites

   • Who can consent?: Admins and users

   • Admin consent display name: HalocoreAdminConsent

   • Admin consent description: Halocore Read and Write

   • State: Enabled

6. Click Add scope. The new scope appears in the list.

7. Copy the generated scope api://halocoreadmin/Config.ReadWrites and save it in a text editor, such as Notepad, for later use.

   

   Client Scope (API scope)

Step 6: Create Roles

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

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

   

   App roles

   • Display name: ROLE_CUSTOMER_ADMIN

   • Allowed member types: Users/Groups

   • Value: ROLE_CUSTOMER_ADMIN

   • Description: CUSTOMER_ADMIN

   • Enable this app role: Selected

3. Repeat these steps to create the ROLE_CUSTOMER_USER role.

4. Click Apply.

   

   Role List

5. The new roles appear in the list.

Step 7: Apply Role to Users

1. In the Microsoft Entra admin center navigation pane, select Enterprise applications.

   1. The Enterprise applications page displays the service principals available in your tenant.

   2. In the search box, enter the application name. For example, enter User Management.

   3. Select the application from the search results. The Overview page opens.

      

      Overview page

   4. Select Assign users and groups. The Users and groups page opens.

   5. On the Users and groups page, click Add user/group. The Add Assignment page opens.

   6. Under Users and groups:

      • Click None Selected.

      • Search for and select a user (for example, John).

        

        Select a user

      • Click Select, and then click Assign.

   7. Under Select a role:

      • Click None Selected.

      • Select ROLE_CUSTOMER_ADMIN.

      • Click Select, and then click Assign.

   8. Repeat these steps to assign the ROLE_CUSTOMER_USER role to additional users. In this example, Derek is assigned the ROLE_CUSTOMER_USER role.

      

      Assigned Roles

Conditions for Running the HaloENGINE GenNXT Tomcat Service

Before running the HaloENGINE GenNXT Tomcat Service, ensure that the following prerequisites are met.

Deny log on as a service policy

If the service runs under a specific user account or 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 is restricted by this policy, the following error message appears when starting the HaloENGINE GenNXT Tomcat Service: “Error 1069: The service did not start due to a logon failure.”

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

During installation, HaloENGINE GenNXT retrieves the required Microsoft Entra ID application details and certificate thumbprint. When the HaloENGINE GenNXT Tomcat Service starts, it connects to the MPIP services by using the details provided 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 during installation must match the thumbprint of the certificate installed in the Local Computer certificate store.

If the service runs under a non-administrative user account, the user might not have sufficient permissions to access the certificate's private key when the certificate is installed in the Local Computer certificate 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 procedure below. Any errors encountered during this process are recorded in the log file. If the verification succeeds, the service continues with initialization.

Prerequisites

• The required certificates (certificate used by MPIP service, root CA, and intermediate CA) are installed.

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

• You have administrator privileges to perform the configuration.

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. Select Computer account, click Next, select Finish, and then click OK.

6. In the left navigation pane, 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-administrator 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

    Result

    The specified non-administrative user can access the certificate's private key, allowing the HaloENGINE GenNXT Tomcat Service to authenticate successfully with MPIP services.

Obtain the HaloENGINE GenNXT License 

Before installing HaloENGINE GenNXT, obtain the license file (license.lic) from Secude Support. The license file enables HaloENGINE GenNXT functionality and defines the licensed features and supported client systems. Only the client systems included in the license are available through their corresponding endpoints.

Use the following table to determine the appropriate license feature set based on your requirements:

Obtaining license

MPIP Authentication

The HaloENGINE Service (MPIP module) requires a certificate for MPIP authentication. Install the certificate in the Local Computer certificate store along with the required Root CA and Intermediate CA certificates.

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

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

Tomcat HTTPS Configuration

Before installing HaloENGINE GenNXT, ensure that the certificate to be used for HTTPS is installed in the Windows Certificate Store on the server where HaloENGINE GenNXT will be installed.

1. Import the self-signed or CA-signed certificate into one of the following certificate stores:

   • Local Computer → Personal → Certificates

   • Current User → Personal → Certificates

2. Identify the alias name of the imported certificate.

3. Open Command Prompt and run the following command: keytool -list -v -storetype Windows-MY

   

   Alias name

4. If an alias is not available, use the Common Name (CN) of the certificate. You can find the Common Name on the certificate Details tab.

   

   Common Name of the certificate

Note: If HaloENGINE GenNXT is installed in the Current User certificate store, ensure that the following conditions are met for the Admin Portal to launch successfully:

1. The HaloENGINE GenNXT Tomcat service runs under the specified user account, not LocalSystem.

2. The certificate is installed in the Current User certificate store of the specified user account.

3. If the specified user does not have logon permission and does not have administrator privileges, install the certificate in the Local Computer certificate store and grant the user access to the certificate's private key. The specified user must have the required minimum privileges. Additionally, update the following file: C:\Program Files\Secude\Tomcat\conf\server.xml.
   Set the certificate keystore type to:

   certificateKeystoreType="Windows-MY-LOCALMACHINE"
   

   

   Sample Server XML

Client Integration and Communication

HaloENGINE GenNXT communicates with supported client systems over HTTPS. The server certificate configured for HaloENGINE GenNXT secures the connection, and the client system must trust the certificate to establish a secure connection. Note: The URL used by the client must match a Subject Alternative Name (SAN) in the certificate. For example, if the client accesses the server using an IP address, the IP address must be included in the certificate SAN.

Client Integration and Certificate Trust

Last updated: October 26, 2026