en-US/about_EntraDeviceReport.help.txt
|
TOPIC about_EntraDeviceReport SHORT DESCRIPTION Read-only reporting on unmanaged and stale device objects in Microsoft Entra ID, via Microsoft Graph. LONG DESCRIPTION EntraDeviceReport queries the Microsoft Graph /devices resource, classifies every registered device object as managed or unmanaged, evaluates each against a configurable staleness threshold, and returns report objects or writes a CSV file. The module performs no writes to any tenant. It reads the current Graph session, reads device objects, and optionally writes one local CSV file. No device is created, modified, retired, or deleted. CLASSIFICATION A device is Managed when isManaged is true AND managementType names a management channel. A device is UnManaged when isManaged is false or null, OR managementType is null or empty. Both booleans derive from one evaluation, so they are always mutually exclusive. The documented managementType value 'unknown' is treated as the absence of a management channel rather than as a channel. Device ownership (company, personal, unknown) is reported as its own column and is not folded into the managed determination. STALENESS A device is stale when approximateLastSignInDateTime is older than the UTC instant StaleAfterDays before the start of the run. A device that has never signed in is treated as stale and is distinguishable by LastSignInKnown being false and DaysSinceLastSignIn being empty. All date arithmetic is UTC. Emitted timestamps are ISO 8601 (yyyy-MM-ddTHH:mm:ssZ) under the invariant culture. AUTHENTICATION Connect-EntraDeviceReport establishes the session and is the only place the module authenticates. One parameter set per method, preferred first: managed identity, workload identity federation via a pre-acquired access token, certificate app-only, environment variables, interactive browser, and client secret as a last resort. -UseDeviceCode is an optional switch on the interactive set only; it is never mandatory and never required by another method. -TenantId is mandatory for every method. Connect-MgGraph accepts it only for the interactive, certificate and client secret flows; for managed identity, access token and environment variable authentication it is verified against the resulting session instead, and a mismatch throws. Get-EntraUnmanagedDeviceReport never signs you in. It inspects the session with Get-MgContext and throws a terminating error naming the missing scopes if the session is absent or under-privileged, so an unattended report run cannot trigger an interactive prompt. Least-privilege scope: Device.Read.All, delegated or application. Directory.Read.All is accepted as a broader alternative, not a default. Both the requested and the validated scope come from one internal source, so they cannot drift apart. COMMANDS Connect-EntraDeviceReport Establishes the Microsoft Graph session. -TenantId is mandatory for every authentication method. Returns the resulting context. Get-EntraUnmanagedDeviceReport Produces the report. Parameters: StaleAfterDays (default 180), Path, IncludeManaged, StaleOnly, PassThru. Supports ShouldProcess, so -WhatIf and -Confirm apply to the CSV write. EXAMPLES Connect-EntraDeviceReport -ManagedIdentity -TenantId '00000000-0000-0000-0000-000000000000' # Unmanaged devices, default 180-day window, to the pipeline Get-EntraUnmanagedDeviceReport -Verbose # Written to CSV Get-EntraUnmanagedDeviceReport -Path './unmanaged-devices.csv' # Stale only, tighter window, objects returned as well as written Get-EntraUnmanagedDeviceReport -StaleAfterDays 90 -StaleOnly -Path './stale.csv' -PassThru # Full estate for reconciliation Get-EntraUnmanagedDeviceReport -IncludeManaged -Path './full-estate.csv' NOTE Requires PowerShell 7.4 or later, and the Microsoft.Graph.Authentication and Microsoft.Graph.Identity.DirectoryManagement modules, 2.0.0 or later. SEE ALSO Get-Help Connect-EntraDeviceReport -Full Get-Help Get-EntraUnmanagedDeviceReport -Full https://github.com/Princetimber/EntraDeviceReport |