HaloITSM

HaloITSM Guides

Documentation to assist with the setup and configuration of the HaloITSM platform

Guides > Azure Active Directory Integration

Azure Active Directory Integration

Azure Active Directory Configuration


This integration allows you to create Users and/or Agents from your Azure Active Directory User list, and also then enable single sign-on with Azure. To get this up and running, you need to register a new application in Azure. You can create a separate application for the import and single sign-on should you wish.


Application Registration


To register a new application in Azure, browse to your Azure Active Directory page and select App Registrations > New Registration. Give your application a sensible name before moving onto choosing what account types should be able to access your application. 


If you are setting the application up for user imports, or single sign-on for one Azure tenant, then choose the first option. If you would like your application to be multi tenanted so that users from multiple Azure tenants can login to Halo via single sign-on, then choose the second option. Please note that multi tenanted apps cannot be used to import users from multiple Azure tenants, and you must instead configure a separate application in each Azure tenant to do this.




The redirect URI can be left blank for now, as multiple redirects can be configured later in the application setup process.


API Permissions


Now that an application has been registered, you must give it the relevant permissions required by the integration. In your new application, go to the API Permissions tab to get started. You should see your list of current permissions will be listed, along with options to manage these. Select the option to add a new permission, and choose Microsoft Graph from the available APIs.



Next select delegated permissions, and select the following permissions from the list:


  • User.Read.All
  • Group.Read.All
  • openid
  • offline_access
  • DeviceManagementManagedDevices.Read.All


Once all permissions have been selected, press the add permissions button to add these to your application. You will notice that some of these permissions require Admin consent before they can be used; admin consent is required for DeviceManagementManagedDevices.Read.All, Group.Read.All and User.Read.All so ensure to press the "Grant admin consent for {COMPANY NAME}" button next to 'Add a permission'. Status column should then be blank. 




Redirect Urls and Authorisation


Next you need to navigate to the Authentication tab within your Azure application, where you can add valid redirect urls. Start by adding a platform and choosing "Web". Once selected, add your Halo web application url as the redirect url and register the platform. This will give you the option to add additional redirect urls.


There are extra redirect urls that must be added for different elements of the integration to work successfully. Using https://halowebapp.com as an example Halo application url that should be replaced with your own url, the following redirect must also be added:

https://halowebapp.com/azure/auth


A further redirect url must be added, that requires you to obtain the authorisation server url of your Halo application. To find the url of your authorisation server, in your Halo application, open Configuration > Integrations > Halo API:



After obtaining the authorisation server url, you must append /account/azureresponse to it, and add this value as redirect url. Using the value from the screenshot above, the redirect url that must be added is http://localhost:49490/account/azureresponse . 


If you have any difficulty obtaining your authorisation server url, please contact the Halo Support Team.


Underneath the area of the Authentication tab where you can register redirect urls for your application, you must ensure that the application is able to issue access tokens and also ID tokens (Used for single sign-on):




General Configuration


To enable the Azure Active Directory integration in Halo, go to Configuration > Integrations, and enable the module. Once the module has been enabled, click the menu icon for the module to begin configuring it.


The Azure Active Directory integration (v2.13.1 and above) allows you to connect to multiple applications/tenants. If you have previously configured the Azure Active Directory integration for Single Sign-On before v2.13.1, you will notice that a default connection has been added for you. This is to ensure the Single Sign-On element of the integration remains active.


You can either choose to edit the default connection, or begin by creating a new connection. This guide will assume that you are creating a new connection. Once you have selected new, you will be presented first with the details tab of your connection, where you can begin by giving your connection a unique name. Next you need to choose the tenant type for your application that you have configured in Azure. If you are using a multi tenanted app for single sign-on, you must add the Azure tenant id for each tenant that you would like to have access to the app.




To find the tenant id in the Azure portal, navigate to the home page of Azure Active Directory where you will see an option for "Tenant information".


Once complete, you then need to add your domain (single tenant only), directory id, application id and application secret. To retrieve the Azure Application and Directory IDs, open Azure and open your configured application. You can find the application ID from the overview page:



From here, navigate to the Certificates and Secrets tab. Underneath the Client Secrets heading, register a new client secret. You can choose whichever expiry length you wish, but keep in mind that you will need to update this value in Halo once it expires and you generate a new secret. You must ensure you take note of this value, as it is not retrievable again after you leave this page.


Although these fields are not all marked with an Asterix to indicate they are mandatory, the integration, including Single Sign-On will not function with any of these fields unpopulated.


Once these options have been configured, the final set of options are to configure Single Sign-on for the connection. Enabling Single Sign-On for a connection will disable it for any previous connection you have enabled it for. Here, you can choose whether Agents and/or Users can use Single Sign-On, and also whether they should be forced to use it, by enabling auto-redirection to the Microsoft login screen.



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. This includes custom fields for Users. If you have created a new connection, some mappings will be displayed by default for you. Should you wish to remove any of the defaults when initially configuring the connection, you should ensure the connection has been saved first, otherwise they will all 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 respectively. For Users, the custom fields must be created in advance – they cannot be created on this screen.


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



Site Mappings


The next tab (Agent/User Mappings) allows you to map subsets of your Azure User list to different Sites/Agent Roles. This is achieved by creating filters for Azure fields, and then choosing which site/agent role the users who are returned within that filter should be created against. To add a new site/agent role mapping, click the plus icon in the top right corner of the table.



The first option lists out all Sites in the Halo database, along with an extra option for *Agent*, if you want to map this filter to an Agent role. If you wish to import your entire user list with no filters, check the “Do not use a filter for this mapping” option. Otherwise, choose an Azure field from the Filter Field dropdown.


Be aware, that filtering on either “group” or “officeLocation” will slow down the loading process when running the import manually. This is due to limitations with filtering in the Microsoft Graph API, so more resource intensive methods of retrieving the users is undertaken.



Filter Type can then be set to one of 2 options – Equals, or Starts With. The only exception to this is when filtering by group, when the only filter type available is Member Of. Finally you need to choose the Filter Value that will be applied to the filter. As an example, the following mapping would retrieve all users that have an officeLocation property that starts with “Stow”:




If you are creating a filter where the site is set to *Agent*, you can choose a role that will be applied to the agent record when imported. This is not a mandatory field, as you can also map Azure Groups to Agent roles, as shown in the next steps.


Once saved, you can review your filter in the table by looking at the friendly filter column. There is also a column for the actual filter.  This displays the actual filter that is passed to the Microsoft Graph API, if the filter property will be used.


Advanced Configuration:


Moving onto the Advanced tab, the first option is a table for Agent Role mappings. This allows you to map groups in Azure Active Directory to Agent Roles in Halo. When importing agents, if they belong to an Azure Group that has a mapping, the corresponding Agent role from the mapping will be applied to their Agent account. This will be added alongside the role specified in the Site mapping in the previous steps.


To add a new Role Mapping, simply hit the add button in the top right corner of the table. You should then type in the name of the Azure Group that you want to map, and then choose the Agent Role that you would like to map it to.



Next is a table for change advice board mappings. This allows you to map groups in Azure Active Directory to change advice boards in Halo. When importing agents, if they belong to an Azure Group that has a mapping, then they will be added to the corresponding change advice board from that mapping. They will also be removed from the change advice board if they are no longer part of the group.


The final section on the advanced configuration tab is for licence management. Enabling this feature allows you to update the status of an agent, based on the roles they are assigned.



Imports


If you are yet to save the Azure Connection, you will now need to do so before the Imports tab becomes enabled. Once saved, the imports tab becomes accessible. On this tab, you can perform manual imports of Users and Agents from Azure, and also configure the Halo Integrator application to run the imports automatically for you.


However, before any importing takes place, you need to provide authorisation to Azure. To do this, click the “Authorise” button under the authorisation heading. This will redirect you to the Microsoft Login screen. Once logged in, and the permissions have been approved, you will be redirected back to the current connection you’re editing.



Once authorised, you can reauthorize using the button shown above. Authorisation can be used for 1 hour when manually importing, at which point, you will need to reauthorise. When the Halo Integrator connects to Azure, it uses a refresh token from your last saved authorisation to redo the authorisation for you. You should ensure that you save your connection after the authorisation has been completed.

If you are importing your user list into the Halo database for the first time, you can now use either of the Import buttons in the next configuration section. If you already have your user list imported, then you should choose at least one user/agent matching field before attempting to import.



By default, when importing from Azure, a User will always be matched to an existing User record in Halo via their unique Azure ID. However, if you already have your User list in your Halo database, but have never imported from Azure before, then Users will not have a unique Azure ID assigned to them, and duplicate users will be created during the import. By choosing at least one matching field, you can prevent duplicate users being created by matching old records on a variety of different fields. The matching process works based on the order in which you add the field to these boxes.

When clicking the Import Users or Import Agents button, Halo retrieves your User list from Azure and filters them according to the mappings you have configured in the previous steps. The Users that are returned will then be displayed on the import screen. Note, that if you have not authorised, or your authorisation has expired, then you will receive a 401 Unauthorised message, and you should reauthorise the application.


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.




The Halo Integrator can be downloaded using the link provided. You can also choose whether to automatically import Users and/or Agents. Each time a connection is synced via the Halo Integrator, the last sync date and the last error (if there was one) will be saved to the connection so that you can view them within the Halo Web Application.


Once you’ve downloaded the Halo Integrator, you should complete the configuration check on the Azure Active Directory Tab. General configuration of the Halo Integrator is not covered in this guide.



If all points return with a green ticket, then you are ready to import. If any points return a red cross, you should revisit the configuration for the integration.


To manually import via the Halo Integrator, switch to the Processes tab and click “Start Processing”. This will process all integrations that are enabled for the Integrator. Alternatively, if your Halo Integrator application is already configured to run on a schedule, the Azure integration will be checked and processed the next time the Integrator runs. 


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.


Single Sign-On Permissions



Troubleshooting


If you see an error message like "Invalid Token" on screen, try the following:

  • Check the user you are logging in as has a mail property.
  • Try logging in with an incognito tab.

Popular Guides

Pin It on Pinterest