#Powerscripting

Skripte / get-entraguestreport

Gastkonten aufräumen

Bewertet alle Gastkonten in Entra ID: nie angenommen, nie angemeldet oder seit Monaten inaktiv.

#Microsoft365PowerShellGet-EntraGuestReport

Auf einen Blick

  • Voraussetzung – Microsoft.Graph-Modul, für die letzte Anmeldung Entra ID P1
  • PowerShell – Windows PowerShell 5.1 oder PowerShell 7
  • Testlauf – liest nur, ändert nichts
  • Installieren – Install-Script Get-EntraGuestReport aus der PowerShell Gallery, Version 1.0.0

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

ParameterAngabeBedeutung
-InactiveDaysoptionalAb wie vielen Tagen ohne Anmeldung ein Gast als inaktiv gilt. Standard: 90.
-PendingDaysoptionalAb wie vielen Tagen eine offene Einladung gemeldet wird. Standard: 30.
-IncludeGroupsoptionalAnzahl der Gruppenmitgliedschaften pro Gast ermitteln.
-ReportPathoptionalOrdner für HTML- und CSV-Bericht. Standard: aktueller Ordner.

03

Beispiele

Beispiel 1
.\Get-EntraGuestReport.ps1

Bewertet alle Gastkonten mit den Standardgrenzen.

Beispiel 2
.\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.

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 }

Weitere Skripte