Get-EntraGuestReport.ps1
|
<#PSScriptInfo
.VERSION 1.0.0 .GUID e52d4fa8-31f3-5b3d-a421-2b63d09c600a .AUTHOR Torsten Weise .COMPANYNAME powerscripting.de .COPYRIGHT (c) 2026 Torsten Weise. MIT-Lizenz. .TAGS Powerscripting German Microsoft365 M365 EntraID AzureAD Graph PSEdition_Desktop PSEdition_Core .LICENSEURI https://powerscripting.de/skripte/files/LICENSE.txt .PROJECTURI https://powerscripting.de/skripte/get-entraguestreport.html .ICONURI https://powerscripting.de/assets/icon-192.png .EXTERNALMODULEDEPENDENCIES .REQUIREDSCRIPTS .EXTERNALSCRIPTDEPENDENCIES .RELEASENOTES Erste Veröffentlichung in der PowerShell Gallery. .PRIVATEDATA #> <# .SYNOPSIS Bewertet alle Gastkonten in Entra ID: nie angenommen, nie angemeldet oder seit Monaten inaktiv. .DESCRIPTION Gäste kommen über Teams, SharePoint-Freigaben und Projekte in den Tenant und gehen selten wieder. Jedes vergessene Gastkonto ist ein Zugang zu Dateien und Teams, den niemand mehr im Blick hat. Wird das Konto beim Partner übernommen, ist der Angreifer auch bei dir drin. Das Skript liest alle Gastkonten und bewertet sie: - Einladung offen: Der Gast hat die Einladung nie angenommen. Älter als -PendingDays ist ein Fall zum Löschen. - Nie angemeldet: Einladung angenommen, aber keine Anmeldung bekannt. - Inaktiv: letzte Anmeldung länger als -InactiveDays her. - Aktiv: alles darunter. Die letzte Anmeldung (signInActivity) liefert Microsoft Graph nur mit einer Entra-ID-P1-Lizenz im Tenant. Ohne diese Lizenz bewertet das Skript nur nach Einladungsstatus und Alter und sagt das im Bericht. Mit -IncludeGroups zeigt es zusätzlich, in wie vielen Gruppen und Teams jeder Gast Mitglied ist. Das kostet einen Aufruf pro Gast. Exitcode: 0 ohne Befund, 1 wenn es Gäste zum Aufräumen gibt. .PARAMETER InactiveDays Ab wie vielen Tagen ohne Anmeldung ein Gast als inaktiv gilt. Standard: 90. .PARAMETER PendingDays Ab wie vielen Tagen eine offene Einladung gemeldet wird. Standard: 30. .PARAMETER IncludeGroups Anzahl der Gruppenmitgliedschaften pro Gast ermitteln. .PARAMETER ReportPath Ordner für HTML- und CSV-Bericht. Standard: aktueller Ordner. .EXAMPLE .\Get-EntraGuestReport.ps1 Bewertet alle Gastkonten mit den Standardgrenzen. .EXAMPLE .\Get-EntraGuestReport.ps1 -InactiveDays 180 -IncludeGroups | Where-Object Bewertung -ne 'Aktiv' Gibt nur die Gäste zum Aufräumen aus, mit Anzahl der Gruppen. .NOTES Autor: Torsten Weise, powerscripting.de Benötigt: Install-Module Microsoft.Graph -Scope CurrentUser Berechtigungen (Zustimmung durch einen Administrator beim ersten Start): User.Read.All, AuditLog.Read.All (für die letzte Anmeldung), GroupMember.Read.All (mit -IncludeGroups) Das Skript liest nur und ändert nichts. Für das regelmäßige Aufräumen eignen sich Zugriffsüberprüfungen (Access Reviews) in Entra ID Governance oder ein Prozess mit dem Fachbereich, der den Gast eingeladen hat. #> #Requires -Modules Microsoft.Graph.Authentication, Microsoft.Graph.Users [CmdletBinding()] param( [ValidateRange(1, 3650)] [int] $InactiveDays = 90, [ValidateRange(1, 3650)] [int] $PendingDays = 30, [switch] $IncludeGroups, [string] $ReportPath = (Get-Location).Path ) $scopes = @('User.Read.All', 'AuditLog.Read.All') if ($IncludeGroups) { $scopes += 'GroupMember.Read.All' } Connect-MgGraph -Scopes $scopes -NoWelcome -ErrorAction Stop $base = 'Id', 'DisplayName', 'Mail', 'UserPrincipalName', 'CreatedDateTime', 'ExternalUserState', 'ExternalUserStateChangeDateTime', 'AccountEnabled', 'CompanyName' $hasSignIn = $true try { $guests = @(Get-MgUser -All -Filter "userType eq 'Guest'" -Property ($base + 'SignInActivity') -ErrorAction Stop) } catch { Write-Host 'Letzte Anmeldung nicht abrufbar (meist fehlt Entra ID P1 oder AuditLog.Read.All). Bewertung nur nach Einladung und Alter.' -ForegroundColor Yellow $hasSignIn = $false $guests = @(Get-MgUser -All -Filter "userType eq 'Guest'" -Property $base) } Write-Host "$($guests.Count) Gastkonten gefunden" $now = Get-Date $i = 0 $rows = foreach ($g in $guests) { $i++ $last = $null if ($hasSignIn -and $g.SignInActivity) { # Interaktive und nicht interaktive Anmeldungen, die jüngere zählt $cand = @($g.SignInActivity.LastSignInDateTime, $g.SignInActivity.LastNonInteractiveSignInDateTime) | Where-Object { $_ } if ($cand) { $last = ([datetime]($cand | Sort-Object -Descending | Select-Object -First 1)).ToLocalTime() } } $created = if ($g.CreatedDateTime) { ([datetime]$g.CreatedDateTime).ToLocalTime() } else { $null } $ageDays = if ($created) { [int]($now - $created).TotalDays } else { $null } $idle = if ($last) { [int]($now - $last).TotalDays } else { $null } $rating = if ($g.ExternalUserState -eq 'PendingAcceptance') { if ($ageDays -ge $PendingDays) { 'Einladung offen' } else { 'Aktiv' } } elseif ($hasSignIn -and -not $last) { if ($ageDays -ge $PendingDays) { 'Nie angemeldet' } else { 'Aktiv' } } elseif ($hasSignIn -and $idle -ge $InactiveDays) { 'Inaktiv' } else { 'Aktiv' } $groups = $null if ($IncludeGroups) { Write-Progress -Activity 'Gruppenmitgliedschaften' -Status $g.DisplayName -PercentComplete (100 * $i / $guests.Count) $groups = @(Get-MgUserMemberOf -UserId $g.Id -All -ErrorAction SilentlyContinue).Count } [pscustomobject]@{ Name = $g.DisplayName Mail = if ($g.Mail) { $g.Mail } else { ($g.UserPrincipalName -replace '#EXT#.*$', '' -replace '_(?=[^_]+$)', '@') } Firma = $g.CompanyName Angelegt = if ($created) { $created.ToString('dd.MM.yyyy') } else { '' } Einladung = switch ($g.ExternalUserState) { 'Accepted' { 'angenommen' } 'PendingAcceptance' { 'offen' } default { $g.ExternalUserState } } 'Letzte Anmeldung' = if ($last) { $last.ToString('dd.MM.yyyy') } elseif ($hasSignIn) { 'nie' } else { 'unbekannt' } 'Tage inaktiv' = $idle Gruppen = $groups Aktiviert = if ($g.AccountEnabled) { 'Ja' } else { 'Nein' } Bewertung = $rating } } if ($IncludeGroups) { Write-Progress -Activity 'Gruppenmitgliedschaften' -Completed } $order = @{ 'Einladung offen' = 0; 'Nie angemeldet' = 1; 'Inaktiv' = 2; 'Aktiv' = 3 } $sorted = @($rows | Sort-Object @{ e = { $order[$_.Bewertung] } }, @{ e = { -1 * [int]$_.'Tage inaktiv' } }, Name) $sorted $stats = $sorted | Group-Object Bewertung | ForEach-Object { "$($_.Name): $($_.Count)" } Write-Host ($stats -join ' | ') $title = "Gastkonten - $($now.ToString('dd.MM.yyyy'))" $css = '<style>body{font-family:Segoe UI,Arial,sans-serif;font-size:13px}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:4px 8px}th{background:#eee}</style>' $src = if ($hasSignIn) { "Inaktiv ab $InactiveDays Tagen ohne Anmeldung." } else { 'Ohne Anmeldedaten (Entra ID P1 fehlt): Bewertung nur nach Einladungsstatus.' } $pre = "<h2>$title</h2><p>$($sorted.Count) Gäste. $($stats -join ', '). $src</p>" $html = $sorted | ConvertTo-Html -Title $title -Head $css -PreContent $pre | Out-String $html = $html -replace '<td>(Einladung offen|Nie angemeldet)</td>', '<td style="background:#f8d7da">$1</td>' ` -replace '<td>Inaktiv</td>', '<td style="background:#fff3cd">Inaktiv</td>' $file = Join-Path $ReportPath ("Gastkonten_{0:yyyy-MM-dd}" -f $now) $html | Set-Content -Path "$file.html" -Encoding UTF8 $sorted | Export-Csv -Path "$file.csv" -NoTypeInformation -Delimiter ';' -Encoding UTF8 Write-Host "Bericht: $file.html und $file.csv" if (@($sorted | Where-Object Bewertung -ne 'Aktiv').Count) { exit 1 } else { exit 0 } |