Zum Inhalt springen
Zurück zum Blog

Ein lesender Tenant-Bericht. Von der Abfrage zur belastbaren Aussage.

Aus der kleinen Eigentümer-Abfrage wird ein Bericht, den auch andere ausführen. Mit Fehlerbehandlung, Kopfdatei, bekannten Lücken und sauberer Aussage.

Microsoft 365SecuritySysadmin
Ein lesender Tenant-Bericht. Von der Abfrage zur belastbaren Aussage.

Im Februar ging es um eine kleine Abfrage. Welche Microsoft-365-Gruppen haben weniger als zwei Eigentümer? Ein paar Zeilen PowerShell, eine CSV. Nachzulesen in Microsoft 365 mit PowerShell prüfen. Lesend starten, Ergebnisse verstehen.

Diese Abfrage beantwortet deine Frage. Für dich, heute, in deinem Kopf.

Sobald jemand anderes sie ausführt oder das Ergebnis in eine Entscheidung fließt, reicht das nicht mehr. Dann muss der Bericht selbst sagen, was er gezählt hat, was er nicht sehen konnte und wo er gescheitert ist.

Technisch kommt dafür wenig dazu. Die Arbeit steckt darin, das Ergebnis ehrlich zu machen.

Was der Bericht nicht sehen kann

Die Lücken gehören auf den Tisch, bevor die erste Zeile läuft. Drei davon kommen von Microsoft Graph selbst.

  • Dienstprinzipale als Eigentümer tauchen nicht auf. Graph v1.0 listet sie nicht. Eine Gruppe, deren einziger Eigentümer eine Anwendung ist, steht im Bericht mit null Eigentümern da.
  • Manche Gruppen haben keine abrufbaren Eigentümer. Das gilt für Gruppen, die in Exchange erstellt wurden, für Verteilergruppen und für Gruppen aus dem lokalen Active Directory.
  • Ohne Leserecht kommt nur das Gerippe. Darf die Sitzung einen Objekttyp nicht lesen, liefert Graph nur Typ und ID. Alle anderen Eigenschaften bleiben leer.

Drei weitere Lücken kommen aus dem Zuschnitt des Skripts. Es betrachtet nur Microsoft-365-Gruppen, keine Sicherheitsgruppen. Ein gesperrtes Konto zählt als Eigentümer. Und es ist eine Momentaufnahme.

Diese Liste reist später im Kopf des Berichts mit. Ein Bericht ohne sie behauptet eine Vollständigkeit, die er nicht hat.

Welche Rechte er braucht

Das Skript läuft delegiert, also im Namen der angemeldeten Person. Es fordert wie im Februar Group.Read.All an, weil es neben den Eigentümern auch Eigenschaften der Gruppen liest.

Die Berechtigung allein reicht nicht. Die angemeldete Person muss in Entra ID auch selbst lesen dürfen. Normale Mitglieder, Gruppeneigentümer und die Rolle Directory Readers dürfen das, Gäste nur eingeschränkt.

Was ein einzelner Befehl mindestens verlangt, zeigt dir Find-MgGraphCommand. Für das reine Auflisten der Eigentümer ist das GroupMember.Read.All.

Soll der Bericht später unbeaufsichtigt laufen, ist eine App-Registrierung mit Anwendungsberechtigung der nächste Schritt. Das ist ein anderes Sicherheitsmodell mit eigener Zustimmung und eigenem Umgang mit Geheimnissen. Darum geht es hier bewusst nicht.

Das Skript

Vier Teile. Anmeldung, Abfrage mit Fehlerbehandlung, Zusammenfassung, Export. Im Tenant wird nur gelesen. Geschrieben wird lokal, in zwei Dateien und bei Fehlern in eine dritte.

#Requires -Modules Microsoft.Graph.Authentication, Microsoft.Graph.Groups

<#
  Lesender Bericht: Microsoft-365-Gruppen und ihre Eigentümer
  Ändert nichts im Mandanten. Schreibt zwei lokale Dateien, bei Fehlern eine dritte.
  Bekannte Lücken: siehe Kopf der Ausgabedatei.
#>

param(
    [string]$Zielordner = '.',
    [switch]$MitNamen   # Eigentümernamen nur auf ausdrücklichen Wunsch exportieren
)

$ErrorActionPreference = 'Stop'
$start = Get-Date

# 1 Anmeldung und Kontext
Connect-MgGraph -Scopes 'Group.Read.All' -NoWelcome
$kontext = Get-MgContext

# 2 Abfrage
$eigenschaften = 'Id','DisplayName','GroupTypes','Visibility','CreatedDateTime',
                 'resourceProvisioningOptions','OnPremisesSyncEnabled'

$gruppen = @(Get-MgGroup -All -Property $eigenschaften |
             Where-Object { $_.GroupTypes -contains 'Unified' })

$bericht = New-Object System.Collections.Generic.List[object]
$fehler  = New-Object System.Collections.Generic.List[object]

foreach ($g in $gruppen) {
    try {
        $eigentuemer = @(Get-MgGroupOwner -GroupId $g.Id -All)
        # Das Team-Kennzeichen hat im v1.0-Modul keine eigene Eigenschaft
        $optionen    = @($g.AdditionalProperties['resourceProvisioningOptions'])

        $zeile = [ordered]@{
            GruppenId         = $g.Id
            Gruppe            = $g.DisplayName
            Team              = $optionen -contains 'Team'
            Sichtbarkeit      = $g.Visibility
            Erstellt          = $g.CreatedDateTime
            Synchronisiert    = [bool]$g.OnPremisesSyncEnabled
            AnzahlEigentuemer = $eigentuemer.Count
            Abfrage           = 'ok'
        }
        if ($MitNamen) {
            $zeile.Eigentuemer = ($eigentuemer |
                ForEach-Object { $_.AdditionalProperties['userPrincipalName'] } |
                Where-Object { $_ }) -join ', '
        }
        $bericht.Add([PSCustomObject]$zeile)
    }
    catch {
        $fehler.Add([PSCustomObject]@{
            GruppenId = $g.Id
            Gruppe    = $g.DisplayName
            Fehler    = $_.Exception.Message
        })
    }
}

# 3 Zusammenfassung
$ende = Get-Date
$kopf = @(
    "Bericht:            Microsoft-365-Gruppen und Eigentümer",
    "Mandant:            $($kontext.TenantId)",
    "Ausgeführt von:     $($kontext.Account)",
    "Berechtigungen:     $($kontext.Scopes -join ', ')",
    "Beginn / Ende:      $start / $ende",
    "Gruppen betrachtet: $($gruppen.Count)",
    "Erfolgreich:        $($bericht.Count)",
    "Mit Fehler:         $($fehler.Count)",
    "",
    "Bekannte Lücken:",
    "- Dienstprinzipale als Eigentümer werden von Graph v1.0 nicht aufgeführt.",
    "- Für in Exchange erstellte, Verteiler- und synchronisierte Gruppen sind Eigentümer nicht verfügbar.",
    "- Gesperrte Eigentümerkonten zählen als Eigentümer.",
    "- Nur Microsoft-365-Gruppen, keine Sicherheitsgruppen.",
    "- Momentaufnahme zum Zeitpunkt der Ausführung."
)

# 4 Export
$stempel = $start.ToString('yyyy-MM-dd_HHmm')
$kopf    | Set-Content (Join-Path $Zielordner "gruppen-eigentuemer_$stempel.txt") -Encoding UTF8
$bericht | Export-Csv  (Join-Path $Zielordner "gruppen-eigentuemer_$stempel.csv") `
           -NoTypeInformation -Encoding UTF8 -Delimiter ';'
if ($fehler.Count -gt 0) {
    $fehler | Export-Csv (Join-Path $Zielordner "gruppen-eigentuemer_$stempel-fehler.csv") `
              -NoTypeInformation -Encoding UTF8 -Delimiter ';'
}

$kopf
Disconnect-MgGraph | Out-Null

Das Skript braucht Version 2 des Graph-Moduls, sonst kennt Connect-MgGraph den Parameter -NoWelcome nicht. Den ersten Lauf machst du in einem Testmandanten oder mit einem Konto, das nur lesen darf.

Und auch hier gilt die Regel aus dem Februar. Erst die Erwartung, dann die Abfrage. Such dir vorher ein Team, das du kennst, und schau nach dem Lauf, ob die Spalte „Team“ bei ihm wirklich True zeigt.

Was gegenüber der Abfrage dazugekommen ist

  • Fehler je Gruppe. Ein try und catch um jede Gruppe sorgt dafür, dass ein einzelner Fehler den Bericht nicht abbricht. Er landet in einer eigenen Datei, statt still zu verschwinden.
  • Drei Zähler. Betrachtet, erfolgreich, mit Fehler. Damit sieht der Leser sofort, ob der Bericht vollständig ist.
  • Eine Kopfdatei. Mandant, Konto, Berechtigungen und Zeitraum. Der Bericht ist ohne das Skript verständlich und einem Lauf eindeutig zuzuordnen.
  • Die Lücken im Kopf. Die Grenzen reisen mit dem Ergebnis.
  • Die Spalte „Synchronisiert“. Sie markiert genau die Gruppen, für die Graph keine Eigentümer liefert.
  • Namen nur auf Wunsch. Ohne -MitNamen enthält der Export keine Personennamen.
  • Die Gruppen-ID in jeder Zeile. Anzeigenamen sind nicht eindeutig.

Wenn Graph bremst

Eine Abfrage je Gruppe erzeugt in großen Tenants viele Aufrufe. Bei Überlast antwortet Microsoft Graph mit Status 429 und einem Retry-After. Die Graph-SDKs werten das selbst aus und warten, deshalb baut das Skript keine eigene Wiederholung ein.

Stehen trotzdem 429er in der Fehlerdatei, holst du diese Gruppen später nach. Für einen Bericht im Quartal ist dieser Ansatz in Ordnung. Für einen täglichen Lauf ist er der falsche. Dafür gibt es Änderungsnachverfolgung und Änderungsbenachrichtigungen, statt immer wieder alles abzufragen.

Die Datei ist ein Dokument

Lesend heißt nicht folgenlos. Mit -MitNamen zeigt die Datei, wer für was verantwortlich ist. Sie gehört in eine Bibliothek mit begrenztem Zugriff und nicht in einen Teams-Chat. Auch ohne Namen ist sie aufschlussreich, denn Gruppennamen verraten Projekte, Kunden und manchmal Personalthemen.

Leg fest, wie lange ein Export bleibt. Den vom Vorquartal brauchst du für den Vergleich. Zwanzig alte Exporte im Downloadordner brauchst du nicht.

Von der Zahl zur Aussage

Ausgabe, Bedeutung und Nachprüfung sind drei verschiedene Dinge. „37 Gruppen ohne zweiten Eigentümer“ ist eine Zahl. Ob das ein Problem ist, hängt davon ab, welche Gruppen es sind.

AusgabeWas du daraus machst
0 EigentümerEinzeln im Admin Center ansehen. Verwaist, Dienstprinzipal oder synchronisiert?
1 EigentümerMit dieser Person einen zweiten Eigentümer abstimmen
2 oder mehrStichprobe, ob die Konten aktiv sind und die Leute ihre Rolle kennen
Abfrage mit FehlerMeldung lesen, später wiederholen, nie als 0 werten
Fehler im Kopf größer 0Bericht ist unvollständig, erst klären, dann berichten

Belastbar wird eine Aussage, wenn sie drei Dinge enthält. Was gezählt wurde, was nicht zu sehen war und was jemand von Hand geprüft hat. Mit Platzhaltern klingt das so. „Von N Microsoft-365-Gruppen meldet der Bericht bei X keinen Eigentümer. Y davon sind synchronisiert, dafür liefert Graph keine Eigentümer. Die übrigen Z haben wir einzeln geprüft.“

Wer den Bericht in den Betriebskalender aufnimmt, hat damit auch gleich den Vermerk für den Quartalstermin. Kopfdatei lesen, Nullen einordnen, Aufgaben an die Fachbereiche verteilen, alten Export löschen.

Einen lesenden Bericht aus einem anderen Bereich findest du im PowerShell - Teams Planner Task Report.

Eine Zahl aus einem Skript ist der Anfang einer Prüfung. Zur Aussage wird sie erst, wenn dabeisteht, was das Skript nicht sehen konnte.

Gruß Micha

Zum Nachlesen

Hat dir der Artikel geholfen? Teile ihn mit deinem Netzwerk.

LinkedIn X