HaloPSA Guides

In this guide we will cover:

- Configuring the Connection between Entra and Halo

- Configuring the Integration within Halo

- Imports

- License Management 

What is the Entra integration used for?

The Entra integration enables identity management within Halo by importing agent and user identities from Microsoft Entra; offering a streamlined identity management within Halo.

Who should use the Entra integration?

This integration is intended for organisations where Microsoft Entra is the primary identity provider, including those using hybrid environments with Entra Connect (formerly AD Sync). SSO providers or secondary sources of identities may also be configured. 

HaloITSM and HaloCRM:

Clients using HaloITSM or HaloCRM will typically rely solely on the Entra integration when Microsoft Entra is their primary identity provider. These organisations generally operate within a single Azure tenant, so a single integration is usually sufficient. However, the integration supports multiple tenants—if relevant identities are distributed across multiple Azure tenants, the configuration steps in this guide can be repeated for each one.

HaloPSA:

HaloPSA clients should use the Entra integration to import staff identities from their own internal tenant where Microsoft Entra is the primary identity provider. For managed customer tenants under the Microsoft Cloud Solution Provider (CSP) program via Partner Center, the Microsoft CSP integration should instead be used to import managed licences, devices, and users.

If a HaloPSA client manages customer tenants outside of the CSP program, the Entra integration can still be used in a multi-tenant fashion as described above, by connecting directly to each managed tenant individually.

Configuring the Connection between Entra and Halo

When connecting to this integration you will see there are a number of authentication methods and credential types to choose from on the integration setup page in Halo. If you are unsure which authentication method and credential type to use, check out our article here: Authentication Methods for Microsoft Integrations.

The simplest and lowest overhead option is to use Application permissions (Client Credentials) as your authentication method and 'Client Secret' as your credential type. 

To configure a connection, you should navigate to the Entra integration within your instance, click 'Add/Edit Tenants' button and click 'New' in the top right of your screen. 

You should then name your connection and choose your authentication method and credential type

You will then be presented with the permissions that need to be configured. At the time of writing, these are the permissions (whether application or delegated) that can be used in the integration. 

Once you have chosen the authentication method, credential type and understand which permissions you need, you can proceed to create an App Registration within your Azure Tenant by following the instructions in Authentication Methods for Microsoft Integrations. 

Instructions to configure the integration with a Secret are included below as this is most commonly used method: 

App Registration Setup

Open the Entra Admin Center (or similar) and navigate to the App Registration section. Click "New Registration".

On the registration screen you will want to fill out:

• Name: Choose something sensible; this won't be visible to users unless used as an SSO provider.
• Supported Account Type: Single tenant
• Redirect URI: The integration setup page/guide will tell you if you need one and the value required. The platform is "Web".

Click "Register". Once registered, copy the "Application (client) ID" and "Directory (tenant) ID" from the Overview tab and store them safely, as these will be needed later.

Remove the default 'User.Read' permission.

Click 'Add a permission', choose the Microsoft Graph API and choose your permission(s). If the permissions on the integration's configuration page and the guide differ, use what the integration page in Halo gives and report this difference to our support team. 

Grant admin consent.

The 'Status' column will change if consent has been successfully granted: 

Once completed, navigate to the "Certificates & secrets" tab, and open the "Client secrets" tab if not already. Click "New client secret", fill out the description and choose an expiry. Microsoft limits this to a maximum of 2 years from creation. Once this generates, copy the "Value" (not Secret ID) and store it securely. It will no longer be visible once you leave this screen.

Return to Halo, add this secret to the secret field along with the Tenant and Application IDs and 'Save'.

Using delegated permissions:

There will be a "Sign in with Microsoft" button. Once pressed, you will be directed to the Microsoft Sign-In screen where you can sign in before being re-directed back to Halo. You will need to sign in with an account with appropriate permissions to access the resources you wish to import; so access to read all users, groups as a minimum and potentially audit logs, organisation data and ability to modify licences if you wish to use those features. 

If the authentication has been successful, the permissions/redirect URIs will have disappeared and the other tabs become accessible (if they weren't before). If unsuccessful, an error will appear in a model windows once re-directed back to Halo.

Using application permissions:

There will be an "Authorise Application" button. Once pressed, the application will attempt authorisation without leaving Halo. 

If successful, the button will disappear and relevant tabs will be unlocked. If unsuccessful, an error code will appear in a modal window.

Halo Connection Configuration

To enable the Azure Active Directory integration in Halo, navigate to Configuration > Integrations, and enable the module. After enabling, click the module's menu icon to start configuring it.

Make sure to enable the module on the integrations page.

Fig 8. Enabling the module.

Single Sign-On (SSO) Configuration

Navigate to Configuration > Integrations > Azure Active Directory, where you'll find settings related to the tenant/application type for Single Sign-On (SSO). You can either edit the default connection or create a new one. If creating a new connection, select "New" and give it a unique name.

In the "Details" tab, choose the tenant type configured in Azure. For multi-tenanted apps in Single Sign-On, add the Azure tenant ID for each tenant you want to access the app. Enter credentials for the App Registration used in this connection. Key configurations to note:

• The "Published" checkbox activates SSO entirely. Enable this to use SSO once configuration is complete.
• The "Allow Single Sign-On for Agents and/or Users" dropdown lets you specify which Halo members can use SSO.
• The "Automatically redirect Agents and Users to Azure without showing the HaloITSM login screen." checkbox forces agents and users to use SSO instead of their Halo credentials.
  • As of v2.179.1+, you can force SSO in the user portal per client/customer by enabling "Redirect to Single-Sign-On option when attempting to log in with Halo credentials" in the customer profile > Settings tab > Self Service Portal dropdown.

Fig 9. Redirect SSO option.

Note: If you are connecting Azure Active Directory for just your organization meaning the "Tenant/Application Type is Single Tenant (HaloITSM in most cases). Then you will be setting up a single tenancy app registration on azure. If you are connecting Azure Active Directory for multiple organizations (mainly used by HaloPSA customers if they are not connecting with CSP. CSP is recommended for syncing customer information to Halo as an MSP - CSP Guide) you should be using a multi tenancy app registration.

Fig 10. SSO redirect option.

Agent/User Import Configuration

Navigate to Configuration > Integrations > Azure Active Directory > Click "Add/Edit Tenants." If you're adding a new connection, click "New." Provide a unique name for the tenant and input the credentials for connecting to your App Registration. Enter the Tenant ID, Application ID, and Azure Application Secret (Value) noted previously and click "Save".

Fig 11. Creating a new Azure connection.

Authorizing Your Connection

Before proceeding with any further configuration, you are required to provide authorization to Azure. Click the "Authorize" button under the "Details" tab. This action redirects you to the Microsoft Login screen. After logging into Azure with a profile with proper permissions to the App Registration, you'll be redirected back to the current connection you're editing in Halo. At this point, the connection to your Azure Active Directory is complete and you can continue configuring how the integration behaves when a sync is actually started.

Halo Integration Configuration

Field Mappings

On the Field Mappings tab of each connection, you can map fields from an Azure User to Halo fields for both Users and Agents, including custom fields for Users. If you've created a new connection, some default mappings will be displayed. To remove any defaults during the initial configuration, save the connection first, or all defaults will be removed.

Click the add icon in the top right corner to add a new field mapping for Users or Agents. This will bring up a screen where you can choose which Azure field should map to which Halo field. Each field can only be used once for Users and Agents. For Users, custom fields must be created in advance; they cannot be created on this screen.

Note: If you are mapping the manager field from Azure to a field in Halo for the user mappings, the value of this field will show as unpopulated on the manual import screen but will be retrieved when the records are actually imported.

Fig 12. Field mappings.

Site Mappings

The next tab, Agent/User Mappings, enables you to map subsets of users from your Azure Active Directory to correlating Sites (for users) or Roles (for agents). This is achieved by building mappings which filter on fields and/or security groups in Azure. To add a new mapping, hit the + symbol in the "Site Mappings" table.

Fig 13. Site mappings.

This will prompt you to choose a mapping type.

Fig 14. Site mapping types.

• Allows you to manually correlate a subset of users from Azure Active Directory to an existing site in Halo
• Upon selection, you are are prompted to... 
  • select a Site to create user profiles against in Halo
  • select a sequence the system will import the mapping in
  • select a user role for users to assume
  • if filtering on Azure group, the exact name of that group
  • whether or not you would like to include external users
  • if filtering on Azure fields, the criteria for matching on users

• As of v2.176.1+, you can map "creationtype" to agents and users. This corresponds with the "User Type" in Entra.
• As of v2.187.1+, you can use this mapping type to map a "License Type" to agents (referring to either named or concurrent licenses in Halo). By default, this is set to "No Change" which is the same behaviour as previously - make agents concurrent if new, do not change them if already existing.

• Allows you to auto-generate a site in Halo against a set Organization based on a field in  Azure Active Directory
• Upon selection, you are are prompted to...
  • select the Organization in Halo to create the new site under
  • select the filter field to group users by and create sites with (value of field will result in site name)
  • select a sequence the system will import the mapping in
  • select a user role for users to assume
  • if filtering on Azure group, the exact name of that group
  • whether or not you would like to include external users
  • if filtering on Azure fields, the criteria for matching on users

Fig 16. Site mappings configuration if mapping to an organisation.

Advanced Configuration

In the Advanced Configuration section, you can set up various role mappings. This allows you to map Azure Active Directory groups to specific Agent/user Roles in Halo so when importing agents/users, if they are part of an Azure Group with a corresponding mapping, the assigned Halo role from this mapping will be applied to their agent/user account. This mapping works in conjunction with the role specified in the site mapping undertaken in the previous steps.

The following entities can be mapped:

• Agent Roles
• User Roles
• Change advise board (CAB)

Agent and User role mappings

Halo agent and user roles can be mapped to Azure groups. Any users in Azure that are a part of this group will be assigned to the mapped agent and user roles when imported into Halo. 

Fig 17. Agent and User role mappings 

Add an entry to a table to configure a mapping. When adding a mapping you will need to type out the exact name of the Azure group then select which Halo agent/user role to map this group to. 

Role for Users with no manager - This setting can be used to have users that do not have a manager in Azure create in Halo with a chosen role. For example, more senior staff may not have a designated manager therefore will like need a role in Halo that gives then a high level of access.  

Change Advise Board Mappings

Here, you can have users in a particular Azure group automatically be added to a CAB in Halo when they are created in Halo. 

Fig 18. CAB mapping

Add a CAB role (v2.186+) - If you check the option to add a CAB role to the mapping, you will be able to choose which CAB role users in this group are created with.

Licence Management 

The last segment in the Advanced Configuration tab pertains to license management. Activating this feature enables you to update the status of an agent based on the roles they are assigned.

Fig 18. Licence management.

When licence management is enabled, you will be able to select agent roles that make agent accounts inactive in Halo. If all Azure users that should not be active in Halo are in the same group, you can map this group to an agent role, then set this agent role to make agents inactive. 

Note: The Agent account will be automatically disabled if the accountEnabled property of the Azure User is false.

Imports

In the Imports tab, you have the option to manually import Users and Agents from Azure. Furthermore, you can set up the Halo Integrator application to perform these imports automatically.

Fig 19. Import configuration.

By default, when importing from Azure, a User is matched to an existing User record in Halo based on their unique Azure ID. If your User list is already in your Halo database, but you haven't imported from Azure before, Users may not have a unique Azure ID assigned, leading to potential duplicate users during the import. To prevent this, choose at least one matching field to avoid duplicates by matching old records on different fields. The matching process follows the order in which you add fields to these boxes.

When you click the "Import Users" or "Import Agents" button, Halo retrieves your User list from Azure, organizes them based on the configured mappings, and displays the returned Users on the import screen. Note that without authorization or if your authorization has expired, you'll receive a 401 Unauthorized message, and you should reauthorize the application. Even if you do not want to import manually within the web app, it is still recommended that you click the Import Agents/Users buttons to check that your mappings are returning the correct subsets of users, before proceeding with an import via the Halo Integrator.

Halo Integrator

Once you’re happy with your configuration for the rest of the connection, you can then enable the connection to be synced via the Halo Integrator application.

Fig 20. Enabling the integrator.

Most customers using Halo Service Solutions have their Halo Integrator hosted for them. In such cases, there's no need for individual customers to host their Integrator for regular synchronization. If you have a specific preference to host your own Halo Integrator, please refer to the related guide for detailed instructions.

Halo Integrator Guide (PSA)

Halo Integrator Guide (ITSM)

Deactivate Users in HaloPSA when they are not found in Azure (Halo Integrator only) (v2.186+) - When enabled users will be deactivated automatically in HaloPSA when they are not found in Azure. If you are using Azure deltas, users will be deactivated when they are deleted from Azure. 

Setting up Multiple integrators

If you have/are setting up more than one Azure tenant, you can configure the Halo integrator to sync different entities (behave differently) for each tenant. 

To do this, enable the integrator for each tenant, on the setup page for each tenant, setting the entities you would like to sync for each tenant. Then in the 'Client ID' field enter the tenant ID you would like this integrator configuration to apply to. 

If you would like the integrator to run for one tenant but not the other, enable the integrator against the tenant you would like it to run for, entering this tenant's ID in the 'Client ID' field. Leave the integrator disabled against the other tenant. 

Note For Older Installations

For versions 2.13.1 and above, the integration allows connections to multiple applications/tenants. If you had configured the integration for Single Sign-On before v2.13.1, a default connection is added to maintain Single Sign-On functionality.

Using delta queries allows the Halo Integrator to retrieve recently updated records only from Microsoft Entra, thus allowing a much more frequent sync of the Halo Integrator. 

Microsoft Entra ID Integration - Delta Queries

Azure delta queries can be activated on the Imports tab of the Microsoft Entra integration setup screen.

Fig 21. Enabling delta queries.

Using the Reset Deltas button you can also reset the current delta saved by the Halo Integrator by either clearing the delta, or getting the latest version of the delta.

Fig 22. Resetting deltas.

Getting the latest delta means that you can instantly start processing the integration on the Halo Integrator much faster, whereas clearing it means the entire directory of users will be processed on the next sync.

For more information on Azure Deltas see our guide here. 

Inbound Logging

Once the functionality is enabled, for each user update that is processed via the Halo Integrator, a more detailed log can be found on the Inbound Requests tab of each integration setup screen. This includes a more detailed log explaining which mappings have been matched, and the result of each individual update notification.

Fig 23. Log example.

Manual imports are not affected by this functionality. The processing of the user update notifications has been designed to align with the manual import, even though the way they are processed is different.

Licence Management in Microsoft Entra ID

This requires adding the "LicenseAssignment.ReadWrite.All" permission to your application and reauthorising your connection.

Once this is done, you will be able to configure the Licence import. A client must be specified for the licences to be imported to, which should match the client the users are imported to. Licences can then be imported manually or via the integrator. Once licences have been imported, subsequent user imports will link the users in Halo to the licences from Entra.

Additionally, you can enable "Allow licences to be managed from within Halo" to allow licences in Entra to be managed from within Halo. When assigning software to a user, you can specify a licence for the software. If this licence is from Entra, it will be added to their account upon saving. Similarly, removing a licence from a user that was imported from Entra will remove that licence in Entra.

Note: This feature should only ever be used with either the CSP integration or Microsoft Entra ID integration, you should never enable it for both integrations.