Microsoft Intune CMDB Integration
Architecture
Scheduled to run once a day by default to get data from Azure based Microsoft Intune, this integration consumes Microsoft Graph API to retrieve selected managed devices data, detected applications and the installation data of those detected applications on the managed devices.
The following are the CMDB data that will be populated from your Microsoft Intune by default:
Intune endpoint | Intune resources | Servicely CMDB table | Description |
|---|---|---|---|
deviceManagement/managedDevices?$filter=deviceType eq 'desktop' or deviceType eq 'surfaceHub' | Managed devices | CMDBDesktop | Desktop CIs |
deviceManagement/managedDevices?$filter=deviceType eq 'winEmbedded' or deviceType eq 'windowsRT' or deviceType eq 'windows10x' | Managed devices | CMDBLaptop | Laptop CIs |
deviceManagement/detectedApps | Detected apps | CMDBEndUserSoftware | The applications/softwares registered on Intune |
deviceManagement/managedDevices('${deviceId}')/detectedApps | App installations | CMDBInstalledSoftware | The installation information of the registered applications/softwares on the registered desktops/laptops. This is retrieved per managed devices by getting the applications installed on them. |
Reference to Intune Managed Devices deviceType options: https://learn.microsoft.com/en-us/graph/api/resources/intune-devices-devicetype?view=graph-rest-beta
Reference to Intune Detected apps (Software) discovered: https://learn.microsoft.com/en-us/mem/intune/apps/app-discovered-apps
Implementation steps
The following outlines high level steps a typical implementation of this Intune integration involves:
- Installing the “integration_microsoft_intune” application and performing an initial setup.
- Set-up authentication from your Servicely environment to your Intune environment.
- Performing an initial one off pull from your Intune to your Servicely.
- Review the CIs that the integration populates.
- Configure to address those review items by making the required tweaks as required.
- Activate the Intune Servicely Job to have the integration running regularly on a pre-defined but configurable, schedule.
Application activation and performing initial setup
Install Intune integration application
- Navigate to Application > Application > Applications and find the application named integration_microsoft_intune.
- Click on the “install application” button at the bottom of the form
Generate Import tables
There are four import table definitions as part of the Microsoft Intune integration. The actual import tables will need to be generated prior to the first run of this integration. To do that, please navigate to Data import > Import > Import staging tables and find the following import table definitions:
IntuneCMDBDesktop |
|---|
IntuneCMDBLaptop |
IntuneCMDBEndUserSoftware |
IntuneCMDBInstalledSoftware |
For each of the above import table definitions, view the record and click on the Generate temporary table button. Example below:
Set-up Authentication (Azure and Servicely)
Azure set-up
- Create and register a Microsoft Entra ID (previously known as Azure AD) app. For more information please refer to Azure configuration
- Add the following Microsoft Graph permissions to the application. Note that each needs to be of type “Application” with “admin consent” granted.
DeviceManagementManagedDevices.Read.All |
|---|
DeviceManagementConfiguration.Read.All |
offline_access |
- Create a Client Secret for it and keep it for now as you need to enter it on Servicely
- Set-up a Redirect URL for it as: https://<instance-name>.servicely.ai/sso/oauth_callback For example, if your instance name is acmecorp, the URL should be https://acmecorp.servicely.ai/sso/oauth_callback
Servicely set-up (System OAuth Provider)
The System OAuth Provider defines the information required to initiate the OAuth2 Authorization, Token exchange, and Token renewal.
You can find more information on the fields and requirements for the System OAuth Provider here: Managed - OAuth2 | OAuth2 Providers
You can use one the supplied out of box templates, on the System OAuth Provider form, called “Microsoft” to fill in the base information.
You will need to fill in the details for:
- Client ID (get from “Application ID” of the Microsoft Entra ID application you had set-up earlier
- Client Secret
- Tenant ID (domain name you set-up the Microsoft Entra ID application in) - to replace [tenant-id] part of both the Authorization URL and the Token URL
- Grant type = Client Credentials
Initially the Authorization URLs populated by the Microsoft template will look like the following:
Replace the [tennant-id] part of the URL with Tenant ID from previous step on Azure setup.
Then the overall System OAuth Provider will look like the following:
Servicely set-up (System API Outbound Token)
The ‘System API Outbound Token’ record tracks the OAuth authorization request. This includes the user the request is to be issued as, along with the ‘scope’ of the privileges assigned to the user.
These tokens are tied to a System OAuth Provider; however, you can have many tokens (each with different credentials and scopes) associated with each provider.
You can find more information on the fields and requirements for the System API Outbound Tokens here: Managed - OAuth2 | System API Outbound Tokens
The only Intune integration specific field you will need to configure is Scopes (value as below).
Field | Value |
|---|---|
Name | MicrosoftIntune |
Scopes | https://graph.microsoft.com/.default |
Once the record is created, you can select the ‘Get authorization token’ button to begin the authorization process with Azure. You will be taken to the Microsoft login page where you need to login as the user you want to use to access your Intune data.
Note that per Microsoft article: How to use Microsoft Entra ID to access Intune APIs in Microsoft Graph - Microsoft Intune , all Intune’s API permission scopes currently require administrator access to authorize.
Once you have authenticated, you will be asked to confirm the permissions being granted. Once the process is completed on Microsoft end, you will then be taken back to Servicely’s System API Outbound Token record. You will notice that the State of the record will change from “New” to “Ready” with the “Expires” date and time auto populated.
Note of the reference document from Microsoft on consent: Consent experience for applications in Microsoft Entra ID - Microsoft identity platform
Servicely Set-up (Set the Token the integration to use)
Now that you have a System API outbound token set-up, you will need to configure the Intune integration property to make use of it.
- Go to the Microsoft Intune property page by navigating to Microsoft Intune > Administration > Properties
- Find a property called “Auth token”
- Select the token you had set-up previously
- Click on Save
Initial one-off pull from Intune into Servicely
- Navigate to Microsoft Intune > Administration > Job
- On the Job record named “Microsoft Intune Integration“, copy the “Script” in there and execute it on the Server script module. Please refer to Server Scripts documentation on how to execute/run one off server side scripts.
Review the CIs that the integration populates
With relevant configuration management stakeholders:
- Check mapped fields are populated by the integration and if needed, review which Intune attributes that are not yet mapped out of box
- Check rough count of laptops/desktop/software CIs vs what your Intune has
- Capture, review and prioritise the results from the review process
Configuration
This section will make references to “Intune integration properties” accessed by navigating to the Microsoft Intune property page by navigating to Microsoft Intune > Administration > Properties
Modify Intune API queries used for managed devices
This step may be required as part of initial configuration to ensure all deviceType possibilities are catered for and your Servicely environment receiving all devices that are needed.
If you only need to pull one of the device types, for example, only Laptop but not Desktop, you should set the “Desktop API endpoint” property to be blank.
On the Intune integration properties, you may modify the following properties to add/remove Graph API queries for the Intune device types you would like synchronised over to Servicely CMDB. Here are the properties:
Property name | Default | Description |
|---|---|---|
Desktop API endpoint | $filter=deviceType eq 'desktop' or deviceType eq 'surfaceHub'&$top=50 | Query to get CIs to push to CMDBDesktop table. NOTE: It is important that we retain the top HTTP parameter to keep the number of devices returned by Microsoft Graph API per page, manageable and not throttled by the Graph API. |
Laptop API endpoint | $filter=deviceType eq 'winEmbedded' or deviceType eq 'windows10x' or deviceType eq 'windowsRT'&$top=50 | Query to get CIs to push to CMDBLaptop table. NOTE: It is important that we retain the top HTTP parameter to keep the number of devices returned by Microsoft Graph API per page, manageable and not throttled by the Graph API. |
Modify/add Intune attributes mapping to Servicely
Here are the Import staging table, Transform map and CMDB tables mapping:
Import staging table | Transform map | CMDB table |
|---|---|---|
IntuneCMDBDesktop | (Intune) CMDB Desktop - API | CMDBDesktop |
IntuneCMDBLaptop | (Intune) CMDB Laptop - API | CMDBLaptop |
IntuneCMDBEndUserSoftware | (Intune) CMDB Software - API | CMDBEndUserSoftware |
IntuneCMDBInstalledSoftware | (Intune) CMDB Installed Software - API | CMDBInstalledSoftware |
Here are the out of box field mappings from Intune to Servicely:
Desktop and Laptop
A field marked as the primary key in the mapping, is used by the integration to identify if a device in Intune needs to update an existing CI in Servicely, or create a new one.
If you need to check against the serial number instead of the Intune device id, mark the Serial number mapping to be the primary key instead.
If there is any mapping you do not need because you do not want Servicely to bring in the particular information from Intune, you can remove the field maping.
Intune attributes | Servicely field names | Primary key |
|---|---|---|
id | Asset ID | Yes |
deviceName | Name | |
model | Model | |
lastSyncDateTime | Last discovered | |
enrolledDateTime | Enrolment date | |
osVersion | Operating system version | |
serialNumber | Serial number | |
manufacturer | Vendor | |
totalStorageSpaceInBytes | Storage | |
wiFiMacAddress | MAC Address | |
operatingSystem | Operating system | |
physicalMemoryInBytes | Memory | |
processorArchitecture | Processor | |
userPrincipalName | End user | |
lastLoggedOnUser | Last logged in user | |
isEncrypted | Encrypted | |
Software
Intune attributes | Servicely field names |
|---|---|
displayName | Name |
softwareVersion | Software version |
To modify/add Intune attributes to map to Servicely:
- Identify the Intune attributes you need Servicely to process
- Identify which CMDB tables and fields you want those Intune fields to be mapped to
- Add the Intune fields you identified in step 1 into the relevant staging import tables. There will be a “Fields” field on the import table definition. Following is example for IntuneCMDBLaptop with an initial set of Intune attributes we had mapped as part of the out of box setup. You will then need to regenerate the import table, by clicking on the "Delete temporary table" button and then the "Generate temporary table" button.
- Add the transform map for those new import fields for the respective staging import and CMDB tables
Import table automated cleanup
It is important to have the import tables used by the integration, regularly cleaned up to avoid unnecessary growth in the database size. For that, the integration comes with the following pre-configured System table cleanup records. They are deactivated by default, but you should review them, update the data retention configuration if required, and then activate.
Name | Table to cleanup | Default data retention |
|---|---|---|
Clean up Intune laptop records | ImpTmpIntuneCMDBLaptop | Max 7 days since creation date/time |
Clean up Intune dekstop records | ImpTmpIntuneCMDBDesktop | Max 7 days since creation date/time |
Clean up Intune software records | ImpTmpIntuneCMDBEndUserSoftware | Max 7 days since creation date/time |
Clean up Intune installed software records | ImpTmpIntuneCMDBInstalledSoftware | Max 7 days since creation date/time |
To update the data retention configuration, please refer to this documentation: System Table Cleanup
Advanced
While all of the Intune integration’s properties, can be updated, in most cases only the following may require changes. Please contact Servicely Support if you have questions on any of them:
Property name | Default value | Description |
|---|---|---|
Graph API version to use | beta | Graph api version used for the intune integration. Choices are either: beta v1.0 |
Max pages | 100 | Maximum pages in Graph API paginated responses that Servicely will handle. This may need to be increased depending on the amount of data on your Intune. |
Interval between consecutive API calls | 120 | Interval in seconds that can be used to space out Graph API calls chained one after another like pagination, to prevent throttling Ref Doc on Microsoft about their Graph API throttling: https://learn.microsoft.com/en-us/graph/throttling-limits, e.g. every 20 seconds there is a max 200 requests for Intune one |
Installed software API structure | device | Microsoft Graph API allows for two different ways to retrieve software installation information, i.e. either by getting software installation off software definitions OR off managed devices. At the present time, the default way we are using is to get software installation per managed device. Choices are either (with order of API executions):
|
Integration’s schedule
The Microsoft Intune integration’s Job that comes with the application runs on a schedule to regularly pull from Intune into Servicely. It is not active by default to give you a chance to do ad-hoc runs and have the resulting data reviewed.
- To update/enable the Job, navigate to Microsoft Intune > Administration > Job
- To update frequency of the Job, update the “Cron expression”. There, you can define frequencies such as running the integration once a day, twice a week, etc. Note that the default is that integration will run once a day at 1AM local time. Please contact Servicely Support of any question.
- To enable the Job, set Active to be “Yes” and click Save. To disable, set Active to be "No" and click Save.
Non production Servicely environments
You should also consider whether you want a clone target instance such as a non production environment to run intune integration at all or to run it at different times. If so, please set-up a System Configuration Script to do that, on your production environment accordingly.