01
Was das Skript macht
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.
02
Parameter
| Parameter | Angabe | Bedeutung |
|---|---|---|
-InactiveDays | optional | Ab wie vielen Tagen ohne Anmeldung ein Gast als inaktiv gilt. Standard: 90. |
-PendingDays | optional | Ab wie vielen Tagen eine offene Einladung gemeldet wird. Standard: 30. |
-IncludeGroups | optional | Anzahl der Gruppenmitgliedschaften pro Gast ermitteln. |
-ReportPath | optional | Ordner für HTML- und CSV-Bericht. Standard: aktueller Ordner. |
03
Beispiele
.\Get-EntraGuestReport.ps1Bewertet alle Gastkonten mit den Standardgrenzen.
.\Get-EntraGuestReport.ps1 -InactiveDays 180 -IncludeGroups | Where-Object Bewertung -ne 'Aktiv'Gibt nur die Gäste zum Aufräumen aus, mit Anzahl der Gruppen.
04
Quellcode
Die Datei ist als UTF-8 mit BOM gespeichert, damit Umlaute auch in Windows PowerShell 5.1 korrekt ankommen. Heruntergeladene Skripte blockiert Windows unter Umständen. Freigeben mit Unblock-File .\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 }War das hilfreich?