# Get Intune Compliance data using PowerShell leveraging Graph API

Getting compliance data from Intune web interface can be a pain in the ass. 

Post from [Ola Strom](https://twitter.com/olastromcom) about [getting compliance data from Intune using Graph API](https://www.olastrom.com/2021/get-more-information-on-device-compliance) inspired me to create PowerShell functions for such task. 

---

# TL;DR
We will create App registration in Azure, grant it correct permissions, and use it for authentication when calling PowerShell functions [New-IntuneAuthHeader](https://github.com/ztrhgf/useful_powershell_functions/blob/master/INTUNE/New-GraphAPIAuthHeader.ps1), [Get-IntuneOverallComplianceStatus](https://github.com/ztrhgf/useful_powershell_functions/blob/master/INTUNE/Get-IntuneOverallComplianceStatus.ps1) and [Get-IntuneDeviceComplianceStatus](https://github.com/ztrhgf/useful_powershell_functions/blob/master/INTUNE/Get-IntuneDeviceComplianceStatus.ps1).

---

# Table of Contents
- [TL;DR](#tldr)
- [Prerequisite](#prerequisite)
- [Function for creating authentication header](#function-for-creating-authentication-header)
- [Function for getting overall compliance data](#function-for-getting-overall-compliance-data)
  - [Example output](#example-output)
- [Function for getting given device compliance data](#function-for-getting-given-device-compliance-data)
  - [Example output](#example-output-1)
- [Useful TIP](#useful-tip)
- [Useful links that inspired me](#useful-links-that-inspired-me)

---

# Prerequisite
To programmatically access Intune API (Graph API), you have to create `App Registration` with correct permissions in your Azure first. I've used this [nice tutorial](https://thesleepyadmins.com/2020/10/24/connecting-to-microsoft-graphapi-using-powershell/) to learn how to do it.

In a nutshell, you have to:
1. Create App Registration
 - Head to https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps > `New registration` > Choose App name and click `Register`
2. Add permission to this App
 - Open your newly created App > `API permissions` > `Add a permission` > Add following `Application` permissions
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626770010271/Y9s-s0OqS.png)
  - Don't forget to `Grant admin consent`
3. Generate App Secret
 - Again in you App settings open `Certificates & secrets` > `New client secret`
Choose validity period and some meaningful description. **Don't forget to safely store generated password**! We will need it later for requests authentication.

---

# Function for creating authentication header
Function [New-IntuneAuthHeader](https://github.com/ztrhgf/useful_powershell_functions/blob/master/INTUNE/New-IntuneAuthHeader.ps1) is prerequisite for any of my following functions. It is used to create an authentication header that is then used to authenticate every REST api request. It requires your tenant name (contoso.onmicrosoft.com), App ID and App Secret (password created earlier) to generate such header.

> 
`Application ID` can be found in `Overview` section of our App
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626770405778/I16YbcKG_.png)
`TenantDomainName` can be found in `Overview` section of your Azure Active Directory as `Primary domain`.

## Function definition
```
function New-IntuneAuthHeader {
    <#
    .SYNOPSIS
    Function for generating header that can be used for authentication of Graph API requests.

    .DESCRIPTION
    Function for generating header that can be used for authentication of Graph API requests.

    .PARAMETER credential
    Credentials for Graph API authentication (AppID + AppSecret).

    .PARAMETER TenantDomainName
    Name of your Azure tenant.

    <yourtenantdomain>.onmicrosoft.com

    .EXAMPLE
    $header = New-IntuneAuthHeader -credential $cred
    $URI = 'https://graph.microsoft.com/v1.0/deviceManagement/managedDevices/'
    $managedDevices = (Invoke-RestMethod -Headers $header -Uri $URI -Method Get).value

    .NOTES
    https://adamtheautomator.com/powershell-graph-api/#AppIdSecret
    https://thesleepyadmins.com/2020/10/24/connecting-to-microsoft-graphapi-using-powershell/
    https://github.com/microsoftgraph/powershell-intune-samples
    #>

    [CmdletBinding()]
    [Alias("Get-IntuneAuthHeader")]
    param (
        [System.Management.Automation.PSCredential] $credential = (Get-Credential -Message "Enter AppID as UserName and AppSecret as Password"),

        [ValidateNotNullOrEmpty()]
        $tenantDomainName
    )

    if (!$credential) { throw "Credential is missing" }

    if (!$tenantDomainName) { throw "TenantDomainName is missing" }

    Write-Verbose "Getting token"

    $body = @{
        Grant_Type    = "client_credentials"
        Scope         = "https://graph.microsoft.com/.default"
        Client_Id     = $credential.username
        Client_Secret = $credential.GetNetworkCredential().password
    }

    $connectGraph = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$tenantDomainName/oauth2/v2.0/token" -Method POST -Body $body

    $token = $connectGraph.access_token

    if ($token) {
        return @{ Authorization = "Bearer $($token)" }
    } else {
        throw "Unable to obtain token"
    }
}
```

---

# Function for getting overall compliance data
Function [Get-IntuneOverallComplianceStatus](https://github.com/ztrhgf/useful_powershell_functions/blob/master/INTUNE/Get-IntuneOverallComplianceStatus.ps1) can be used to get compliance data for your whole environment. 

This means it will return you a combination of these three Intune pages as one object.

**Overall Compliance status:**
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626775947770/r6sS6RJd-.png)
**Specific Compliance policy setting:**
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626776212099/0cpNYs4Rz.png)
**Problematic device compliance:**
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626776270329/poi5Dsu8X.png)

## Function definition
```
function Get-IntuneOverallComplianceStatus {
    <#
    .SYNOPSIS
    Function for getting overall device compliance status from Intune.

    .DESCRIPTION
    Function for getting overall device compliance status from Intune.

    .PARAMETER header
    Authentication header.

    Can be created via New-IntuneAuthHeader.

    .PARAMETER justProblematic
    Switch for outputting only non-compliant items.

    .EXAMPLE
    $header = New-IntuneAuthHeader
    Get-IntuneOverallComplianceStatus -header $header

    Will return compliance information for all devices in your Intune.

    .EXAMPLE
    $header = New-IntuneAuthHeader
    Get-IntuneOverallComplianceStatus -header $header -justProblematic

    Will return just non-compliant information for devices in your Intune.
    #>

    [CmdletBinding()]
    param (
        [hashtable] $header
        ,
        [switch] $justProblematic
    )

    if (!$header) {
        # authenticate
        $header = New-IntuneAuthHeader -ErrorAction Stop
    }

    # helper hashtable for storing devices compliance data
    # just for performance optimization
    $deviceComplianceData = @{}

    # get overall compliance policies per-setting status
    $URI = 'https://graph.microsoft.com/v1.0/deviceManagement/deviceCompliancePolicySettingStateSummaries'
    $complianceSummary = (Invoke-RestMethod -Headers $header -Uri $URI -Method Get).value
    $complianceSummary = $complianceSummary | select @{n = 'Name'; e = { ($_.settingName -split "\.")[-1] } }, nonCompliantDeviceCount, errorDeviceCount, conflictDeviceCount, id

    if ($justProblematic) {
        # preserve just problematic ones
        $complianceSummary = $complianceSummary | ? { $_.nonCompliantDeviceCount -or $_.errorDeviceCount -or $_.conflictDeviceCount }
    }

    if ($complianceSummary) {
        $complianceSummary | % {
            $complianceSettingId = $_.id

            Write-Verbose $complianceSettingId
            Write-Warning "Processing $($_.name)"

            # add help text, to help understand, what this compliance setting validates
            switch ($_.name) {
                'RequireRemainContact' { Write-Warning "`t- devices that haven't contacted Intune for last 30 days" }
                'RequireDeviceCompliancePolicyAssigned' { Write-Warning "`t- devices without any compliance policy assigned" }
                'ConfigurationManagerComplianceRequired' { Write-Warning "`t- devices that are not compliant in SCCM" }
            }

            # get devices, where this particular compliance setting is not ok
            $URI = "https://graph.microsoft.com/v1.0/deviceManagement/deviceCompliancePolicySettingStateSummaries/$complianceSettingId/deviceComplianceSettingStates?`$filter=NOT(state eq 'compliant')"
            $complianceStatus = (Invoke-RestMethod -Headers $header -Uri $URI -Method Get).value

            if ($justProblematic) {
                # preserve just problematic ones
                $complianceStatus = $complianceStatus | ? { $_.state -ne "compliant" }
            }

            # loop through all devices that are not compliant (get details) and output the result
            $deviceDetails = $complianceStatus | % {
                $deviceId = $_.deviceId
                $deviceName = $_.deviceName
                $userPrincipalName = $_.userPrincipalName

                Write-Verbose "Processing $deviceName with id: $deviceId and UPN: $userPrincipalName"

                #region get error details (if exists) for this particular device and compliance setting
                if (!($deviceComplianceData.$deviceName)) {
                    Write-Verbose "Getting compliance data for $deviceName"
                    $deviceComplianceData.$deviceName = Get-IntuneDeviceComplianceStatus -deviceId $deviceId -justProblematic -header $header
                }

                if ($deviceComplianceData.$deviceName) {
                    # get error details for this particular compliance setting
                    $errorDescription = $deviceComplianceData.$deviceName | ? { $_.setting -eq $complianceSettingId -and $_.userPrincipalName -eq $userPrincipalName -and $_.errorDescription -ne "No error code" } | select -ExpandProperty errorDescription
                }
                #endregion get error details (if exists) for this particular device and compliance setting

                # output result
                $_ | select deviceName, userPrincipalName, state, @{n = 'errDetails'; e = { $errorDescription } } | sort state, deviceName
            }

            # output result for this compliance setting
            [PSCustomObject]@{
                Name                    = $_.name
                NonCompliantDeviceCount = $_.nonCompliantDeviceCount
                ErrorDeviceCount        = $_.errorDeviceCount
                ConflictDeviceCount     = $_.conflictDeviceCount
                DeviceDetails           = $deviceDetails
            }
        }
    }
}
```

## Example output
By calling:
```
$header = New-IntuneAuthHeader
Get-IntuneOverallComplianceStatus -header $header -justProblematic
```
You will get:
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626769066542/mzUKY2MAM.png)
Output is a classic object, so you can format or filter it as you wish...

---

# Function for getting given device compliance data
Function [Get-IntuneDeviceComplianceStatus](https://github.com/ztrhgf/useful_powershell_functions/blob/master/INTUNE/Get-IntuneDeviceComplianceStatus.ps1) can be used to get specific device(s) compliance data. 

## Function definition
```
function Get-IntuneDeviceComplianceStatus {
    <#
    .SYNOPSIS
    Function for getting device compliance status from Intune.

    .DESCRIPTION
    Function for getting device compliance status from Intune.
    Devices can be selected by name or id. If omitted, all devices will be processed.

    .PARAMETER deviceName
    Name of device(s).

    Can be combined with deviceId parameter.

    .PARAMETER deviceId
    Id(s) of device(s).

    Can be combined with deviceName parameter.

    .PARAMETER header
    Authentication header.

    Can be created via New-IntuneAuthHeader.

    .PARAMETER justProblematic
    Switch for outputting only non-compliant items.

    .EXAMPLE
    $header = New-IntuneAuthHeader
    Get-IntuneDeviceComplianceStatus -header $header

    Will return compliance information for all devices in your Intune.

    .EXAMPLE
    $header = New-IntuneAuthHeader
    Get-IntuneDeviceComplianceStatus -header $header -deviceName PC-1, PC-2

    Will return compliance information for PC-1, PC-2 from Intune.
    #>

    [CmdletBinding()]
    param (
        [string[]] $deviceName,

        [string[]] $deviceId,

        [hashtable] $header,

        [switch] $justProblematic
    )

    $ErrorActionPreference = "Stop"

    if (!$header) {
        # authenticate
        $header = New-IntuneAuthHeader -ErrorAction Stop
    }

    if (!$deviceName -and !$deviceId) {
        # all devices will be processed
        Write-Warning "You haven't specified device name or id, all devices will be processed"
        $deviceId = (Invoke-RestMethod -Headers $header -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices?`$select=id" -Method Get).value | select -ExpandProperty Id
    } elseif ($deviceName) {
        $deviceName | % {
            #TODO limit returned properties using select filter
            $id = (Invoke-RestMethod -Headers $header -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices?`$filter=deviceName eq '$_'" -Method Get).value | select -ExpandProperty Id
            if ($id) {
                Write-Verbose "$_ was translated to $id"
                $deviceId += $id
            } else {
                Write-Warning "Device $_ wasn't found"
            }
        }
    }

    $deviceId = $deviceId | select -Unique

    foreach ($devId in $deviceId) {
        Write-Verbose "Processing device $devId"
        # get list of all compliance policies of this particular device
        $deviceCompliancePolicy = (Invoke-RestMethod -Headers $header -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices('$devId')/deviceCompliancePolicyStates" -Method Get).value

        if ($deviceCompliancePolicy) {
            # get detailed information for each compliance policy (mainly errorDescription)
            $deviceCompliancePolicy | % {
                $deviceComplianceId = $_.id
                $deviceComplianceStatus = (Invoke-RestMethod -Headers $header -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices('$devId')/deviceCompliancePolicyStates('$deviceComplianceId')/settingStates" -Method Get).value

                if ($justProblematic) {
                    $deviceComplianceStatus = $deviceComplianceStatus | ? { $_.state -ne "compliant" }
                }

                $name = (Invoke-RestMethod -Headers $header -Uri "https://graph.microsoft.com/beta/deviceManagement/manageddevices('$devId')?`$select=deviceName" -Method Get).deviceName

                $deviceComplianceStatus | select @{n = 'deviceName'; e = { $name } }, state, errorDescription, userPrincipalName , setting, sources
            }
        } else {
            Write-Warning "There are no compliance policies for $devId device"
        }
    }
}
```

## Example output
By calling:
```
$header = New-IntuneAuthHeader
Get-IntuneDeviceComplianceStatus -deviceName ni-20-ntb, ng-34-ntb -header $header -justProblematic
```
You will get:
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626769385795/YlgLcnVhI.png)
Output is a classic object, so you can format or filter it as you wish...

---

# Useful TIP
Don't forget that you can get Graph URI for your request just by opening Intune page in your browser and using `Developer mode` (F12)! 
![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1626772777085/fHCKTgoyce.png)

---

# Useful links that inspired me
- https://adamtheautomator.com/powershell-graph-api/#AppIdSecret
- https://thesleepyadmins.com/2020/10/24/connecting-to-microsoft-graphapi-using-powershell/
- https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter
- https://github.com/microsoftgraph/powershell-intune-samples