HaloCRM Guides
Microsoft CSP Integration
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.
CSP: Common Errors
Error | Solution |
Compact Token Parsing Error | Disconnect the application by going to the detail tab and editing then clicking on the disconnect button and Reauthorise (You will need to log back into azure, which will require an azure admin login) |
Calling Application Error | make sure GDAP has been selected for each customer mapping that requires it (You can check by clicking the edit symbol beside each tenant on the tenant mappings table and selecting GDAP on the dropdown). The "Grant Admin Consent" button must be used to sign in to the partner centre for each client, using the admin email. This is how the tenants are authenticated, it must be a login per tenant that has GDAP enabled and there must be a prompt for 2FA/ MFA. Some tenants, may not be using GDAP, you can check which ones are on the microsoft partner centre. |
Parameter Length Error | You have accidentally copied the secret key instead of the secret value, the secret value from azure should be entered into the halo secret input, this is the second value from the right on the client secret screen in the Azure App Registration. |
Token expiration | The Secret Value has expired: Create a new client secret on azure and then disconnect app on halo, update to the new client secret on halo then reauthorise the application on Halo. The secret key expiry may be on the multi tenant app registration or the single tenant app registration. You can find out which one has expired by going to the respective app registrations in Azure and the secret that has expired will be marked with a red symbol. |
Insufficient Privileges: During Site Mappings | Make sure you have logged in with an admin account for the tenant that is getting this error (error will tell you what tenant is causing the issue) and that you were prompted for a code via 2FA/ MFA when signing into the admin account on the partner centre. A succesful login will take you back to the CSP integration list on halo (This doesn't guarantee that it has worked). |
AD user not found | When trying to SSO to the user portal, if you get this error it is because the user has not been given any web access level to the user portal, if you go the permissions tab of the user (far left tab) and give them a "Web Access Level". If this is a standard user it is Recommended to give them the single select option "This Users Tickets" on the Web Access Level dropdown. |
Redirect URI specified does not match redirect configured | Make sure the redirects are correct: Single Tenant App Registration Redirect URI: https://examplehalo.halopsa.com/azure/auth Multi Tenant App Registration Redirect URI: https://examplehalo.halopsa.com/config/integrations/microsoftcsp |
Required scopes requested by app… | This error can occur when authorising the single tenant app registration, you need to select the correct user_impersonation, to do so make sure you have selected the correct API Permission on the single tenant setup. NB: There should only be one API Permission on the list for the single tenant app registration. |
Client has requested acess to a resource not listed | Guide for the error |
Neither tenant is B2C or tenant doesn't have premium license | Are you trying to import the users last sign-in date? Try turning that option off and retesting the problematic tenants. Accessing the last signin date requires a P1/P2 license, which is likely why you are receiving that error. |
Failed to retrieve users - Token refresh failed - invalid_client - AADSTS7000229: The client application X...X is missing service principal in the tenant Y...Y. | Click 'Grant Admin Consent' and re-authorize |
Popular Guides
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments, Teams and Roles
- Halo Integrator
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- NHServer Deprecation User Guide
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Suppliers