AsBuiltReport.Microsoft.Intune

0.1.0

Src/Private/Get-AbrIntuneTenantOverview.ps1

function Get-AbrIntuneTenantOverview {
    <#
    .SYNOPSIS
    Documents the Microsoft Intune tenant overview and licensing summary.
    .DESCRIPTION
        Collects and reports on:
          - Tenant identity (name, ID, domains)
          - Intune licence summary
          - MDM Authority configuration
          - Device platform breakdown
    .NOTES
        Version: 0.1.0
        Author: Pai Wei Sing
    #>
    [CmdletBinding()]
    param (
        [Parameter(Position = 0, Mandatory)]
        [string]$TenantId
    )

    begin {
        Write-PScriboMessage -Message "Collecting Intune Tenant Overview for $TenantId."
        Show-AbrDebugExecutionTime -Start -TitleMessage 'Tenant Overview'
    }

    process {
        Section -Style Heading1 'Tenant Overview' {
            Paragraph "The following section provides a summary of the Microsoft Intune configuration for tenant $TenantId."
            BlankLine

            try {
                # Tenant identity
                $OrgResp = Invoke-MgGraphRequest -Method GET `
                    -Uri "$($script:GraphEndpoint)/v1.0/organization?$select=id,displayName,verifiedDomains,countryLetterCode,preferredLanguage,createdDateTime" `
                    -ErrorAction Stop
                $Org = if ($OrgResp.value) { $OrgResp.value[0] } else { $OrgResp }

                $DefaultDomain = ($Org.verifiedDomains | Where-Object { $_.IsDefault }).Name
                $Domains       = ($Org.verifiedDomains | ForEach-Object { $_.Name }) -join ', '

                $tenantInObj = [ordered] @{
                    'Tenant Name'        = $Org.displayName
                    'Tenant ID'          = $Org.id
                    'Default Domain'     = $DefaultDomain
                    'Verified Domains'   = $Domains
                    'Country / Region'   = if ($Org.countryLetterCode) { $Org.countryLetterCode } else { '--' }
                    'Preferred Language' = if ($Org.preferredLanguage) { $Org.preferredLanguage } else { '--' }
                    'Created Date'       = if ($Org.createdDateTime) { ($Org.createdDateTime).ToString('yyyy-MM-dd') } else { '--' }
                }
                $TenantObj = [System.Collections.ArrayList]::new()
                $TenantObj.Add([pscustomobject](ConvertTo-HashToYN $tenantInObj)) | Out-Null

                $TableParams = @{ Name = "Tenant Details - $TenantId"; List = $true; ColumnWidths = 40, 60 }
                if ($Report.ShowTableCaptions) { $TableParams['Caption'] = "- $($TableParams.Name)" }
                $TenantObj | Table @TableParams

                #region MDM Authority
                try {
                    # Use /beta without $select -- field support varies; read full object and extract what's available
                    $MdmAuth = Invoke-MgGraphRequest -Method GET `
                        -Uri "$($script:GraphEndpoint)/beta/deviceManagement" `
                        -ErrorAction SilentlyContinue
                    if ($MdmAuth) {
                        $mdmObj = [ordered] @{
                            'MDM Authority'      = 'Microsoft Intune'
                            'Subscription State' = if ($MdmAuth.subscriptionState) { $MdmAuth.subscriptionState } else { '--' }
                            'Tenant ID'          = if ($MdmAuth.id)                { $MdmAuth.id }                else { '--' }
                        }
                        $MdmTable = [System.Collections.ArrayList]::new()
                        $MdmTable.Add([pscustomobject]$mdmObj) | Out-Null
                        $MdmTableParams = @{ Name = "MDM Authority - $TenantId"; List = $true; ColumnWidths = 45, 55 }
                        if ($Report.ShowTableCaptions) { $MdmTableParams['Caption'] = "- $($MdmTableParams.Name)" }
                        $MdmTable | Table @MdmTableParams
                    }
                } catch {
                        if (Test-AbrGraphForbidden -ErrorRecord $_) {
                            Write-AbrPermissionError -Section 'MDM Authority' -RequiredRole 'Intune Service Administrator or Global Administrator'
                        } else {
                            Write-AbrSectionError -Section 'MDM Authority' -Message "$($_.Exception.Message)"
                        }
                    }
                #endregion

                #region Intune Licence Summary
                try {
                    $Skus = Get-MgSubscribedSku -ErrorAction SilentlyContinue
                    $IntuneSKUs = @('INTUNE_A', 'INTUNE_EDU', 'EMS', 'EMSPREMIUM', 'SPE_E3', 'SPE_E5',
                        'M365EDU_A3_FACULTY', 'M365EDU_A5_FACULTY', 'ENTERPRISEPREMIUM',
                        'ENTERPRISEPACK', 'DEVELOPERPACK_E5')
                    if ($Skus) {
                        $SkuObj = [System.Collections.ArrayList]::new()
                        foreach ($Sku in ($Skus | Sort-Object SkuPartNumber)) {
                            $skuInObj = [ordered] @{
                                'SKU / License'   = $Sku.SkuPartNumber
                                'Total Units'     = $Sku.PrepaidUnits.Enabled
                                'Assigned Units'  = $Sku.ConsumedUnits
                                'Available Units' = ($Sku.PrepaidUnits.Enabled - $Sku.ConsumedUnits)
                                'Status'          = $Sku.CapabilityStatus
                            }
                            $SkuObj.Add([pscustomobject]$skuInObj) | Out-Null
                        }
                        $SkuTableParams = @{ Name = "License Summary - $TenantId"; ColumnWidths = 35, 16, 16, 16, 17 }
                        if ($Report.ShowTableCaptions) { $SkuTableParams['Caption'] = "- $($SkuTableParams.Name)" }
                        $SkuObj | Table @SkuTableParams

                        # Excel
                        if (Get-IntuneExcelSheetEnabled -SheetKey 'LicenseSummary') {
                            $script:ExcelSheets['License Summary'] = $SkuObj
                        }
                    }
                } catch {
                        if (Test-AbrGraphForbidden -ErrorRecord $_) {
                            Write-AbrPermissionError -Section 'License Summary' -RequiredRole 'Intune Service Administrator or Global Administrator'
                        } else {
                            Write-AbrSectionError -Section 'License Summary' -Message "$($_.Exception.Message)"
                        }
                    }
                #endregion

            } catch {
                    if (Test-AbrGraphForbidden -ErrorRecord $_) {
                        Write-AbrPermissionError -Section 'Tenant Overview' -RequiredRole 'Intune Service Administrator or Global Administrator'
                    } else {
                        Write-AbrSectionError -Section 'Tenant Overview' -Message "$($_.Exception.Message)"
                    }
                }
        }
    }

    end {
        Show-AbrDebugExecutionTime -End -TitleMessage 'Tenant Overview'
    }
}