Graph API for Architects: The Endpoints That Actually Matter

# App-only auth (certificate) — preferred for automation
Connect-MgGraph -ClientId $appId -TenantId $tenantId -CertificateThumbprint $thumbprint
 
# Or interactive auth for ad-hoc work (delegated)
Connect-MgGraph -Scopes "User.Read.All","Group.Read.All","Device.Read.All",
    "DeviceManagementManagedDevices.Read.All","Policy.Read.All",
    "Directory.Read.All","SecurityEvents.Read.All","Reports.Read.All",
    "AuditLog.Read.All"

# Pull core counts
$users = Get-MgUser -All -Property "Id,UserType,AccountEnabled" -ConsistencyLevel eventual -CountVariable userCount
$groups = Get-MgGroup -All -Property "Id,GroupTypes,SecurityEnabled,MailEnabled"
$devices = Get-MgDevice -All -Property "Id,OperatingSystem,TrustType"
$managedDevices = Get-MgDeviceManagementManagedDevice -All -Property "Id,OperatingSystem,ComplianceState"
 
# User breakdown
$members = ($users | Where-Object { $_.UserType -eq "Member" }).Count
$guests = ($users | Where-Object { $_.UserType -eq "Guest" }).Count
$disabled = ($users | Where-Object { -not $_.AccountEnabled }).Count
 
# Group breakdown
$m365Groups = ($groups | Where-Object { $_.GroupTypes -contains "Unified" }).Count
$securityGroups = ($groups | Where-Object { $_.SecurityEnabled -and $_.GroupTypes -notcontains "Unified" }).Count
$dynamicGroups = ($groups | Where-Object { $_.GroupTypes -contains "DynamicMembership" }).Count
 
# Device breakdown
$entraJoined = ($devices | Where-Object { $_.TrustType -eq "AzureAd" }).Count
$hybridJoined = ($devices | Where-Object { $_.TrustType -eq "ServerAd" }).Count
$intuneEnrolled = $managedDevices.Count
$compliant = ($managedDevices | Where-Object { $_.ComplianceState -eq "compliant" }).Count
 
Write-Host "=== Tenant Summary ==="
Write-Host "Users: $($users.Count) (Members: $members, Guests: $guests, Disabled: $disabled)"
Write-Host "Groups: $($groups.Count) (M365: $m365Groups, Security: $securityGroups, Dynamic: $dynamicGroups)"
Write-Host "Entra Devices: $($devices.Count) (Entra Joined: $entraJoined, Hybrid: $hybridJoined)"
Write-Host "Intune Enrolled: $intuneEnrolled (Compliant: $compliant, Non-compliant: $($intuneEnrolled - $compliant))"
Write-Host "Entra-to-Intune gap: $($devices.Count - $intuneEnrolled) devices registered but not managed"

$policies = Get-MgIdentityConditionalAccessPolicy -All
 
# Summary analysis
$enabled = ($policies | Where-Object { $_.State -eq "enabled" }).Count
$reportOnly = ($policies | Where-Object { $_.State -eq "enabledForReportingButNotEnforced" }).Count
$disabled = ($policies | Where-Object { $_.State -eq "disabled" }).Count
 
Write-Host "CA Policies: $($policies.Count) (Enabled: $enabled, Report-Only: $reportOnly, Disabled: $disabled)"
 
# Flag policies with broad exclusions
$broadExclusions = $policies | Where-Object {
    $_.Conditions.Users.ExcludeGroups.Count -gt 0 -or
    $_.Conditions.Users.ExcludeUsers.Count -gt 3
} | Select-Object DisplayName, State,
    @{Name="ExcludedUsers"; Expression={$_.Conditions.Users.ExcludeUsers.Count}},
    @{Name="ExcludedGroups"; Expression={$_.Conditions.Users.ExcludeGroups.Count}}
 
if ($broadExclusions) {
    Write-Host "`nPolicies with broad exclusions (review these):"
    $broadExclusions | Format-Table -AutoSize
}
 
# Export full policy set to JSON for version control
$policies | ConvertTo-Json -Depth 10 | Out-File "ca-policies-export.json"
Write-Host "`nFull policy export written to ca-policies-export.json"

# Get all active directory role assignments
# Note: Graph limits $expand to one property per query, so we expand separately
$roleAssignments = Get-MgRoleManagementDirectoryRoleAssignment -All -ExpandProperty "roleDefinition"
 
# Build a clean summary — resolve principal display names via the directory
$privilegedUsers = foreach ($ra in $roleAssignments) {
    $principal = Get-MgDirectoryObject -DirectoryObjectId $ra.PrincipalId
    [PSCustomObject]@{
        Role          = $ra.RoleDefinition.DisplayName
        Principal     = $principal.AdditionalProperties.displayName
        PrincipalType = $principal.AdditionalProperties.'@odata.type' -replace '#microsoft.graph.',''
    }
}
 
# Flag Global Admins specifically
$globalAdmins = $privilegedUsers | Where-Object { $_.Role -eq "Global Administrator" }
Write-Host "Global Administrators: $($globalAdmins.Count)"
$globalAdmins | Format-Table Principal, PrincipalType -AutoSize
 
# Count assignments by role
$privilegedUsers | Group-Object Role | Sort-Object Count -Descending |
    Select-Object @{Name="Role";Expression={$_.Name}}, Count |
    Format-Table -AutoSize

# Get latest Secure Score
$scores = Get-MgSecuritySecureScore -Top 1 -Sort "createdDateTime desc"
$latest = $scores[0]
 
Write-Host "Current Secure Score: $($latest.CurrentScore) / $($latest.MaxScore)"
$pct = if ($latest.MaxScore -gt 0) { [math]::Round(($latest.CurrentScore / $latest.MaxScore) * 100, 1) } else { 0 }
Write-Host "Percentage: ${pct}%"
 
# Find top 5 improvement actions by potential score increase
$improvements = $latest.ControlScores |
    Where-Object { $_.Score -lt $_.ScoreInPercentage } |  # Not fully implemented
    Sort-Object @{Expression={$_.ScoreInPercentage - $_.Score}; Descending=$true} |
    Select-Object -First 5 @{Name="Control"; Expression={$_.ControlName}},
        @{Name="Current"; Expression={$_.Score}},
        @{Name="Max"; Expression={$_.ScoreInPercentage}},
        @{Name="Potential Gain"; Expression={$_.ScoreInPercentage - $_.Score}}
 
Write-Host "`nTop 5 improvement actions:"
$improvements | Format-Table -AutoSize

$managedDevices = Get-MgDeviceManagementManagedDevice -All `
    -Property "DeviceName,OperatingSystem,ComplianceState,LastSyncDateTime,UserPrincipalName"
 
$complianceSummary = $managedDevices | Group-Object ComplianceState |
    Select-Object @{Name="State"; Expression={$_.Name}}, Count |
    Sort-Object Count -Descending
 
$complianceSummary | Format-Table -AutoSize
 
# Devices that haven't synced in 30+ days — likely stale
$staleDevices = $managedDevices | Where-Object {
    $_.LastSyncDateTime -and $_.LastSyncDateTime -lt (Get-Date).AddDays(-30)
}
 
Write-Host "Devices not synced in 30+ days: $($staleDevices.Count)"

# Get MFA registration details
$mfaStatus = Get-MgReportAuthenticationMethodUserRegistrationDetail -All
 
# Get enabled member users (exclude guests and disabled accounts)
$enabledUsers = Get-MgUser -All -Filter "accountEnabled eq true and userType eq 'Member'" `
    -Property "Id,UserPrincipalName,Department" -ConsistencyLevel eventual
 
# Cross-reference: enabled users without MFA
$mfaGaps = foreach ($user in $enabledUsers) {
    $registration = $mfaStatus | Where-Object { $_.Id -eq $user.Id }
    if ($registration -and -not $registration.IsMfaRegistered) {
        [PSCustomObject]@{
            UPN        = $user.UserPrincipalName
            Department = $user.Department ?? "Unset"
            MfaRegistered = $false
            MethodsRegistered = ($registration.MethodsRegistered -join ", ")
        }
    }
}
 
Write-Host "Enabled members without MFA: $($mfaGaps.Count) of $($enabledUsers.Count)"
 
# Group by department for the report
$mfaGaps | Group-Object Department |
    Select-Object @{Name="Department"; Expression={$_.Name}},
        Count |
    Sort-Object Count -Descending |
    Format-Table -AutoSize

$skus = Get-MgSubscribedSku -All
 
# SKU friendly name lookup
$skuNames = @{
    "ENTERPRISEPREMIUM"     = "Microsoft 365 E5"
    "ENTERPRISEPACK"        = "Microsoft 365 E3"
    "SPE_E5"                = "Microsoft 365 E5 (unified)"
    "SPE_E3"                = "Microsoft 365 E3 (unified)"
    "EMSPREMIUM"            = "EMS E5"
    "Microsoft_365_Copilot" = "Microsoft 365 Copilot"
    "SPB"                   = "Microsoft 365 Business Premium"
}
 
$summary = $skus | Where-Object { $_.AppliesTo -eq "User" -and $_.PrepaidUnits.Enabled -gt 0 } |
    Select-Object @{Name="Licence"; Expression={ $skuNames[$_.SkuPartNumber] ?? $_.SkuPartNumber }},
        @{Name="Purchased"; Expression={$_.PrepaidUnits.Enabled}},
        @{Name="Assigned"; Expression={$_.ConsumedUnits}},
        @{Name="Available"; Expression={$_.PrepaidUnits.Enabled - $_.ConsumedUnits}},
        @{Name="Utilisation"; Expression={
            [math]::Round(($_.ConsumedUnits / $_.PrepaidUnits.Enabled) * 100, 1)
        }}
 
$summary | Sort-Object Licence | Format-Table -AutoSize
 
# Flag under-utilised paid SKUs
$underUtilised = $summary | Where-Object {
    $_.Utilisation -lt 70 -and $_.Licence -notmatch "Free|Trial"
}
 
if ($underUtilised) {
    Write-Host "`nUnder-utilised paid licences (below 70%):"
    $underUtilised | Format-Table -AutoSize
}