HaloCRM Guides

Introduction

This integration allows you to import all of your partner customers from Microsoft CSP, and then retrieve all licences/users associated with each customer. To do this, two applications must be registered in the Azure portal of your Azure tenant. The need for two Azure app registrations is to allow accommodate for GDAP customer relationships within your Partner Center.

For Halo to be able to read License/Subscription data from the CSP API one of the below GDAP Roles are required
GDAP roles

• Directory Reader
• Global Reader
• User Administrator
• License Administrator

Both Single Tenant & Multi-Tenant app registrations are required here (details outlined below) - the Single Tenant app registration will be used to connect to the partner center & retrieve your managed Tenants & associated Licences, but will not have permission to access users/devices within those tenants, this is what the Multi-tenant app registration is needed for - to access users/devices.

NB For the Single Tenant Partner Center app, you need to consent with a user who has Partner Center access AND permanent delegated admin (and relevant GDAP permissions) to all tenants.

In Halo, navigate to Configuration > Integrations > Microsoft CSP, enable the module and then click into the module to open the configuration screen.  Initially, you will see a section titled "Creating an Azure Application". This section holds some basic details to assist with configuring the first application in your Azure portal. This will be covered in much more detail in the next section of this guide.

Registering an Azure Application

To begin configuring an Azure application, open your Azure portal, select Azure Active Directory and then navigate to App registrations > New registration. Give your application a sensible name and select "Accounts in this organizational directory only (Single Tenant)" as the supported account type.

To finalise your application registration, you must register a redirect URI. Although this step is optional at the time of submission, a redirect URI is required for the integration to work successfully. The redirect you are required to add can be found in the "Creating an Azure Application" section of the Halo interface.

Once the application has been registered successfully, navigate to the Certificates & secrets tab. Register a new client secret using the available options. Once created, keep a copy of this secret somewhere safe, as it is not obtainable again once you leave the application.

The final step to registering your Azure app is to add specific API permissions so that your app can access certain resources/APIs. Navigate to the API permissions tab, where you will see that you have the permission User.Read by default. This permission can be removed as it is not required. Select Add a permission & switch to the 'APIs my organization uses' tab. Select "Microsoft Partner Center" and then add "user_impersonation" to the application. 

If you cannot see the Microsoft Partner Center API permission for user_impersonation, this is because your account is not recognised as an indirect provider or a Direct bill partner. You can workaround this by adding the ID fa3d9a0c-3fb0-42cc-9193-47c7ecd2edbd into the applications search bar, which will then show a selectable user_impersonation permission.

Now all required permissions have been added to the application, on the API permissions page, click the "Grant admin consent" option to grant these permissions to the application.

Authorizing the Application in Halo

Now your Azure application is fully configured, open the Microsoft CSP integration setup screen in Halo, and populate the fields under the Details/Azure Application for Microsoft Partner Center sections using the values generated when creating you application. 

Save & click "Authorize Application" to connect to the application. Please make sure that the account used to authorize the integration has multi-factor authentication enabled in Azure, and has partner rights to access tenants . Otherwise an unauthorized error may occur on the import screen. 

(When you authorise CSP you NEED to have the MFA prompt - if there is no prompt because of conditional access for certain IPs for example then the app will not be authorised as MFA is a requirement when you Authorise it) This MUST be Azure MFA only and specifically using a Strong method (TOTP/Authenticator App)

Registering A Second (Multi-Tenant) Application

After successfully authorising the first Application, you will be presented with some further details required for a second Application that needs to be created:

 Again, head to the App Registrations section of your Azure Portal & create a new App Registration. This time, select your 'Supported Account Type' as 'Accounts in any organizational directory (Any Azure AD directory - Multitenant)':

You will need to add the new redirect URI into this second application. This will follow a format similar to: https://<YOUR HALO URL>/config/integrations/microsoftcsp

As with the previously created Application, you will need to generate a secret & store this somewhere, as you will not have access to this once you leave the application set up page. 

Head to the API permissions section of the App Registration & select Microsoft Graph>Application Permissions:

& add the permissions mentioned in the 'Creating an Azure Application' section:

Once you have added your API permissions in, ensure you Grant Admin Consent.

Elevate the Application's Permissions

Now that your multi tenant application has been created, you must elevate the permissions of the application so that it can access data in your customers' Azure tenants. This must be done via PowerShell. Run the following PowerShell script, which can also be found in the "Creating a Partner-Managed Application" section in Halo. You must replace {yourAppsId} with the ID of the application you have just registered. (If you have not previously installed the AzureAD module, you will need to run the following script first: Install-module AzureAD) 

Connect-AzureAd
$group = Get-AzureADGroup -Filter "displayName eq 'Adminagents'"
$sp = Get-AzureADServicePrincipal -Filter "appId eq '{yourAppsId}'"
Add-AzureADGroupMember -ObjectId $group.ObjectId -RefObjectId $sp.ObjectId

Common Error: 

This may be caused by the scripting environment you are using

"WARNING Get-AzureADGroup is not found. The most similar Azure PowerShell command is: Get-AzADGroup"

If you receive this error above, use:

"""

Connect-AzureAd
$group = Get-AzADGroup -Filter "displayName eq 'Adminagents'"
$sp = Get-AzADServicePrincipal -Filter "appId eq '{yourAppsId}'"
Add-AzADGroupMember -ObjectId $group.ObjectId -RefObjectId $sp.ObjectId

"""

The PowerShell script adds the service principal that represents your application to the Adminagents group in your tenant.

Finally, add the details from this App registration into the remaining fields present on the details tab (Application ID, Application Secret) of the CSP integration, under the 'Azure Application for Azure Active Directory & Intune' section.

NB: It should be noted that this method (using 2 Azure Application Registrations) was introduced into Halo as of V2.108 to support GDAP relationships. If you have set up the CSP integration prior to 2.108, you will have a single application used for the integration. To support GDAP relations, you will need to create a new multi-tenant Azure application (following the steps above) with the API permissions & Redirect URI as per:

This application will need to have it's application permissions elevated (outlined above). Once you have created this new application, add the Application ID & Secret into the 'Azure Application for Azure Active Directory and Intune' section.

Customer Imports

Once successfully connected, some new tabs will be made available:

The first tab - Tenants, Licences & Subscriptions - is where you go to import your managed CSP Tenants into Halo as customers & import licences against respective tenants/customers. Existing customers will be updated if their Azure tenant id or name matches the record from CSP. You can manually assign an Azure tenant id to a customer record in Halo by navigating to the settings tab of a customer, where the field can be found under the "Microsoft Details" header.

You will also see an option to set the default relationship type for new tenants imported into Halo: DAP or GDAP. For those tenants using GDAP, you must grant Admin consent within the tenant in order to allow Halo to access users. When selecting a tenant's relationship type as GDAP, you will be presented with a 'grant Admin Consent' option. When clicking this, you will be redirected to the Tenant's login page, where you must log in as an Administrator within the tenant itself (i.e, not your Partner Center admin account, but the admin account for that particular tenant)

You will also have to select your licence import types, if you wish to use the two options including 'Your Subscriptions' then you will require a Microsoft Gold/Tier 1 Membership, so if you do not have this microsoft membership level please select 'All Subscribed SKUs'.

Before importing, if you are using top levels in Halo, you can also choose a top level to assign customers to. Clicking the "Import Customers" button will open the importer screen where you can then initialize the import. Licenses will be retrieved when each customer is imported and assigned to the customer record in Halo. These will be visible on the Software Licenses tab of the customer. If you are using Single-Sign on for the Self-Service Portal, based on a multi-tenant Azure App Registration, you can have the tenants imported via CSP automatically added to the SSO 'allowed tenants' list.

Site Mappings

Similarly to the Azure Active Directory integration, you can create site mappings to map subsets of your customers' users into different sites. For the CSP integration, only customers with an Azure tenant id can be mapped to. See the Azure Active Directory integration guide for more information on configuring site mappings.

You can automatically generate a mapping for each customer using the "Generate Mappings" button. This creates a mapping with no filter, which will import every user from the partners Azure Active Directory into one site. These mappings can be modified after they have been generated if you wish to refine them in any way. 

To prevent having to run this function every time a new customer is added, you can enable the ability to automatically create a site mapping in the same way whenever an Azure tenant id is assigned to a customer (via the 'Tenants, Licences & Subscriptions' tab)

User Field Mappings and Imports

Similarly to the Azure Active Directory integration, Azure fields can be mapped to Halo fields. See the Azure Active Directory integration guide for more information on configuring field mappings.

During a user import, existing users will be updated if their unique Azure id matches an existing users Azure id. This field is non-editable in the Halo interface, and will only be populated if you have previously used the Azure Active Directory integration. If you have not used the Azure Active Directory integration before, you can specify which fields you would like to use as a matching identifier. These fields are name, email address and network login. The order of the matching will work in the order in which you add them to the field. For the matching to be successful, you must ensure that you have created a field mapping to each of these Halo fields.

There is also an option to ignore the accountEnabled property of each Azure user. This means users will not be made inactive during a sync.

You also are provided with the option to specify an Azure group, whereby users not in a group with this name will be created as Service Accounts (and hence cannot have Tickets logged against them & will not count to any auto calculated billing quantities). Users that are part of multiple groups will still be created as active users as long as they at least exist in the specified group.

Once you are happy with your configuration, click the "Import Users" button to bring up the importer screen to begin the import. Licenses will be assigned to the user record in Halo if the license exists against the customer. These are visible on the Software Licenses tab of the user.

NB: you may find that, upon importing users/devices, you find the below error:

"the identity of the calling application cannot be established"

This error is caused when the Azure application's application permissions have not been granted admin consent by an administrator. This should happen automatically for customer relationships that use the DAP permission structure, but sometimes this is not the case. GDAP relationships require the user to manually grant the admin consent. 

This can be resolved by doing either of the following:

• GDAP - follow the above instructions regarding GDAP, where you must grant admin consent for each Azure tenant.
• DAP - sign into the Azure portal for the partner tenant as an admin. Navigate to enterprise apps, locate the app that is registered in your own Azure tenant for the CSP integration, open it, and go to the permissions tab. Click the button at the top of the screen that says Grant admin consent.

Halo Integrator

Once you’re happy with all configuration, you can then enable the Halo Integrator for the application, which allows you to perform the imports on a recurring sync. The Halo Integrator can be downloaded using the link provided.

Once the Halo Integrator has been downloaded, complete the configuration check on the Microsoft CSP tab of the Halo Integrator. General configuration of the Halo Integrator is not covered in this guide.

If all points return a green tick, 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 Microsoft CSP integration will be checked and processed the next time the Integrator runs. 

Single Sign-On

To set up single sign-on you will need to set up an Azure Active Directory integration with multi-tenancy, and make sure you have access to all of your clients' tenants.

Error Logging

Errors are logged to the IntegrationError Table.

If you receive this error when running the PowerShell script you will need to run "Install-module AzureAD" first and then re-run the PowerShell Script.

What is GDAP?

GDAP (Granular Delegated Admin Privileges) is a security feature recently introduced by Microsoft.

Before the introduction of GDAP, the CSP integration would connect to all tenant directories via one single account. This meant that one single account had access to every customer & every user within every customer. So if this account got compromised through a cyberattack, then the attacker would have access to every single user. GDAP combats this by enforcing Admin Consent to be granted per tenant. So even with this one 'master account', you would still not have access to all users by default.

This is also why you need to go into each tenant separately, then grant admin consent (whereas before you would grant admin consent once & this would apply to all tenants). So now a cyber attack would need to compromise every admin account in every respective tenant, instead of only one account.

Most Azure Tenants will be using GDAP now, so it is important to make sure there is the correct connection to them on the Microsoft Partner Centre. There should be a login for each customer when you grant admin consent, 2FA/ MFA should also be prompted when you login to the admin account for each tenant, as microsoft requires 2FA/ MFA to authenticate the login. the format of the admin login username is admin@company.com.

As of v2.139 the last sign-in date can now be added as a mapping in the Microsoft CSP and Azure Active Directory integrations

For this to function correctly the API Application in Azure must be given the AuditLog.Read.All permission in addition to the current permissions required, this is a Delegated permission. You can enable this setting in the Azure Active Directory tab of the CSP integration. This setting will throw an error if any of your customers do not have a premium license, accessing the last signin date requires a P1/P2 license.

Marking unlicenced Users as Service Users

As of v2.147 there is the option to mark users that don't include one of the licences in the multi select list shown in the image below, as service users. 

The use case of this is that you can input the licences that you have in your system to decide which users should be marked as active when synced from CSP, and any other user will be marked as a service user.

Any users checked on as service users, will not be included when billing by user count on creation is in user for your recurring invoices. This means if you bill using this method, any users that no longer have licences in the Partner Centre will be removed from automated billing, as the 'Service User' checkbox will be ticked on when they sync back over via CSP without one of the licences selected in the list. 

Microsoft CSP Delta Queries

Using delta queries allows the Halo Integrator to retrieve recently updated records only from Microsoft Entra currently, thus allowing a much more frequent sync of the Halo Integrator, the user changes can sync without the need to update their entire user profile, drastically reducing sync times. The delta functionality is currently only available for the Microsoft Entra (Users) portion of the Microsoft CSP integration. This will be extended to other entities in future releases.

The functionality can be enabled on the Halo Integrator tab of the Microsoft CSP integration setup screen. The delta reset option is also availble here once the record is saved.

In addition to this, the delta can be reset for an individual tenant on the Tenants tab of the integration setup screen.

For more information on Delta Queries, please refer to this Guide: Azure Delta's

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.

Additional Information

• 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 CSP

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

Additionally, you can enable "Allow licences to be managed from within Halo" to allow licences in CSP 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 CSP, it will be added to their account upon saving. Similarly, removing a licence from a user that was imported from CSP will remove that licence in CSP.

NB: 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.

CSP: Common Errors