HaloITSM

HaloITSM Guides

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

Guides > Azure Active Directory Integration

Azure Active Directory Integration

This integration enables you to generate Users and/or Agents directly from your Azure Active Directory User list, and subsequently enables single sign-on with Azure. To start this process, you must register a new application in Azure. You have the option to create a distinct application for both the import and single sign-on if desired.


Azure Connection Configuration


App Registration


To register a new application in Azure, navigate to your Azure Active Directory page and select "App Registrations > New Registration." Provide a meaningful name for your application before proceeding to specify which account types should have access to your application.


If you are configuring the application for user imports or single sign-on for a specific Azure tenant, choose the first option. If you want your application to be accessible across multiple Azure tenants, allowing users from different tenants to log in to Halo via single sign-on, then opt for the second option. Keep in mind that multi-tenanted apps cannot be used to import users from multiple Azure tenants. In such cases, you must configure a separate application in each Azure tenant.




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.



The necessary Graph API Permissions are listed below, with notes detailing their essential functions for the integration to work correctly:


User.Read.All

  • Allows the app to access the full set of profile properties, reports, and managers of other users within your organization.
  • Facilitates a comprehensive view of user information, ensuring effective user profile management.
  • Necessary for the app to act on behalf of the signed-in user in reading extensive user data.

Group.Read.All

  • Enables the app to list groups, read their properties, and access all group memberships on behalf of the signed-in user.
  • Essential for reading calendar, conversations, files, and other group content for all groups accessible to the signed-in user.
  • Supports effective group management within the Halo ITSM/PSA Solution.

Openid

  • Allows users to sign in to the app with their work or school accounts.
  • Permits the app to access basic user profile information, enhancing the authentication process.
  • A fundamental permission for enabling secure and seamless user access to Halo ITSM/PSA Solution.

offline_access

  • Grants the app the ability to see and update data even when users are not actively using the app.
  • Does not provide additional permissions but ensures continuous access to data previously granted.
  • Essential for maintaining data synchronization and system functionality during periods of user inactivity.

DeviceManagementManagedDevices.Read.All

  • (Only necessary if intending to synchronize device-related information, such as from Intune.)
  • Permits the app to retrieve information on all managed devices within the device management scope.
  • Essential for accessing detailed data about managed devices, including properties, status, and configurations.
  • Necessary for effective device management and monitoring within the Halo ITSM/PSA Solution.




Once all permissions have been chosen, click the "Add Permissions" button to incorporate them into your application. Please be aware that certain permissions, namely DeviceManagementManagedDevices.Read.All, Group.Read.All, and User.Read.All, mandate Admin consent before they can be utilized. To grant admin consent, press the "Grant admin consent for {COMPANY NAME}" button next to 'Add a permission'. Following this step, the Status column should display as blank.





Redirect URLs and Authorization


In the Authentication tab of App Registration, add valid redirect URIs. Begin by selecting "Web" as the platform, and register your Halo web application URL as the initial redirect URI. This registration allows you to include additional redirect URIs based on your specific requirements.


For integration functionality, specific redirect URIs are required:

  • User Portal Single Sign-On (SSO):
    • <Halo Web App User Portal URL>/auth/account/azureresponse
  • Agent Portal Single Sign-On (SSO):
    • <Halo Web App Agent Portal URL>/auth/account/azureresponse
  • User/Agent Import:
    • <Halo Web App Agent URL>/azure/auth


Note: URLs starting with <URL>/auth assume a commonly used authorization URL. Keep in mind that this URL may vary for on-premise installations of Halo. If experiencing issues with SSO functionality, double-check and confirm the correct authorization URL, accessible in the Agent portal under Configuration > Integrations > Halo API.




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


After adding the redirect URIs, please ensure both ID and Access Tokens are available for the Azure application. ID Tokens are essential for single sign-on, while Access Tokens are used for the user/agent import. If you prefer to create two separate applications—one for each process—simply choose ID Tokens for single sign-on and Access Tokens for imports. This ensures the correct functionality for your specific needs.




Halo Connection Configuration


Credentials

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.


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.


You can edit the default connection or create a new one. Assuming you're creating a new connection, select "New" and start by giving 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.




To locate the tenant ID in the Azure portal, go to the home page of Azure Active Directory and find the "Tenant information" option.


Afterward, add your domain (for single tenant only), directory ID, application ID, and application secret. Retrieve the Azure Application and Directory IDs by opening Azure and accessing your configured application. The application ID can be found on the overview page.



From here, navigate to the Certificates and Secrets tab, and under the Client Secrets section, register a new client secret. Choose an expiry length, but remember to update this value in Halo when it expires. Take note of the secret value as it cannot be retrieved again after leaving this page.


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


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


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, the value of this field will show as unpopulated on the manual import screen but will be retrieved when the records are actually imported.



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.


This will prompt you to choose a mapping type.


  • "Map to an existing Site"
    • 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
      • screenshot shown below:
    • Note, this site mapping type is used for importing agents. Simply select the site value of *agent* and fill out the mapping just as you would for the users. These Azure Active Directory users will be imported as Agents as well as users when the integration sync runs.
  • "Map to an existing Organization based on an Azure field"
    • 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
      • screenshot shown below:



Advanced Configuration


In the Advanced Configuration section, you can set up Agent Role mappings. This feature enables you to map Azure Active Directory groups to specific Agent Roles in Halo. When importing agents, if they are part of an Azure Group with a corresponding mapping, the assigned Agent Role from this mapping will be applied to their Agent account. This mapping works in conjunction with the role specified in the Site mapping undertaken in the previous steps.


To create a new Role Mapping, click the "Add" button located in the top right corner of the table. Enter the name of the Azure Group you want to map, and then choose the desired Agent Role for the mapping.



The following section in the Advanced Configuration tab involves Change Advice Board mappings. This feature permits you to map Azure Active Directory groups to specific change advice boards in Halo. During agent imports, if agents are associated with an Azure Group with a mapping, they will be added to the designated change advice board from that mapping. Conversely, if they are no longer part of the group, they will be removed from the change advice board.


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.



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.



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.




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.


Popular Guides

Pin It on Pinterest