Search-UnifiedAuditLog stopt in 2027: migreer auditautomatisering naar Microsoft Graph

Microsoft maakt de Microsoft Graph AuditLogQuery-API algemeen beschikbaar voor programmatische bevraging van het Microsoft Purview-auditlog. Tegelijk kondigt Microsoft aan dat de Exchange Online PowerShell-cmdlet Search-UnifiedAuditLog op 15 oktober 2027 stopt. Organisaties die de cmdlet in scripts, rapportages, forensische onderzoeken of eigen integraties gebruiken, moeten die automatisering dus tijdig ombouwen.

Dit is geen aanwijzing dat auditing zelf nu wordt uitgezet. De aangekondigde wijziging gaat specifiek over programmatische opvraging met Search-UnifiedAuditLog. Het risico zit in de koppelingen die ongemerkt van die cmdlet afhankelijk zijn: een dagelijks exportscript, een compliance-rapport, een SOC-runbook of een interne applicatie kan na de einddatum geen auditresultaten meer ophalen als er niets verandert.

Wat verandert er precies?

De nieuwe route loopt via de Microsoft Graph-resource /security/auditLog/queries. Een toepassing maakt eerst een auditLogQuery met de gewenste periode en filters. De query heeft daarna een status, zoals running, succeeded of failed. Pas wanneer de query klaar is, leest de toepassing de bijbehorende records uit via /security/auditLog/queries/{id}/records.

Dat patroon is wezenlijk anders dan een PowerShell-script dat een cmdlet uitvoert en de resultaten direct door de pijplijn verwerkt. Bouw de vervanger daarom als een taak met een wachtrij: query indienen, de status gecontroleerd uitlezen, pas daarna records pagineren en een checkpoint vastleggen. Zo kan een proces veilig hervatten als een run wordt onderbroken.

Voor wie heeft dit impact?

De wijziging is relevant voor organisaties die Search-UnifiedAuditLog zelf aanroepen, ook indirect. Denk aan PowerShell-scripts in Azure Automation of een geplande taak, maatwerk voor incidentonderzoek, periodieke exports naar een datawarehouse en interne compliance-rapportages. Kijk niet alleen in de centrale scriptrepository: de cmdlet komt vaak ook voor in beheeraccounts, runbooks, ticketbijlagen en leveranciersscripts.

Een organisatie die de cmdlet niet gebruikt, hoeft voor deze uitfasering geen migratie uit te voeren. Wel is dit een goed moment om vast te leggen welke auditgegevens geautomatiseerd worden opgehaald, welke bewaartermijn daarvoor geldt en wie eigenaar is van de koppeling. Zonder die inventaris blijft een stuk operationele of bewijsvoering-gerelateerde automatisering gemakkelijk buiten beeld.

Rechten en beschikbaarheid zorgvuldig beoordelen

De AuditLogQuery-API gebruikt Microsoft Graph-machtigingen. Microsoft documenteert zowel productgerichte machtigingen, bijvoorbeeld voor Exchange, SharePoint, OneDrive of Entra, als de bredere machtiging AuditLogsQuery.Read.All. Kies het kleinst mogelijke bereik dat het beoogde scenario dekt, leg de reden van de beheertoestemming vast en laat een app-registratie en die toestemming via het normale wijzigingsproces beoordelen.

Controleer ook de cloud waar de toepassing draait. In de actuele Graph-documentatie staat de API als beschikbaar voor de wereldwijde Microsoft 365-cloud; US Government L4, US Government L5 (DoD) en Microsoft 365 beheerd door 21Vianet staan daar niet als ondersteund. Neem die beperking mee in een ontwerp voor een internationale of multitenantomgeving en ga niet uit van één identieke implementatie voor alle clouds.

Capaciteit en foutafhandeling zijn onderdeel van de migratie

De limieten gelden op tenantniveau, dus voor alle toepassingen samen. Microsoft noemt als basisallocatie ten minste 200 ingediende query’s per voortschrijdend venster van 24 uur en ten minste 50 query’s die tegelijk in de wachtrij staan of draaien. Voor één query geldt een basislimiet van ten minste 1.000.000 records. Hogere capaciteit is mogelijk, maar Microsoft publiceert niet hoe die toekenning precies wordt berekend.

Een query die de recordlimiet bereikt, kan de status succeeded krijgen. Controleer daarom expliciet isRecordCountLimitExceeded; een vergelijking tussen een benaderd recordaantal en de limiet is volgens Microsoft niet betrouwbaar. Splits grote onderzoeken desnoods op in kleinere tijdvakken of specifiekere filters. Bij HTTP-status 429 Too Many Requests moet de toepassing de opgegeven Retry-After-waarde volgen, of anders een exponentieel oplopende wachttijd (back-off) toepassen. Meteen opnieuw proberen vergroot juist de kans op herhaalde throttling.

Praktische migratieaanpak

Inventariseer het gebruik. Zoek naar Search-UnifiedAuditLog, maar ook naar wrapperfuncties en modules die de cmdlet aanroepen. Leg per script vast welke gegevens worden opgehaald, hoe vaak dit gebeurt, wie eigenaar is en welke vervolgprocessen ervan afhangen.
Classificeer de query’s. Breng periode, Microsoft 365-onderdeel, bewerking, gebruiker, object en verwacht volume in kaart. Kies daarna de kleinst noodzakelijke Graph-machtiging en laat die via de bestaande beveiligings- en toestemmingsprocedure goedkeuren.
Bouw een asynchroon verwerkingsproces. Laat dit proces een query aanmaken, de status met een beheerst interval controleren en de records pas verwerken wanneer de definitieve status succesvol is. Sla de query-id, de uitgevoerde filters en een technisch log op, zodat een onderzoek reproduceerbaar blijft.
Ontwerp voor limieten. Centraliseer indien mogelijk het indienen van query’s per tenant, bewaak het aantal actieve taken en implementeer Retry-After en een exponentieel oplopende wachttijd. Controleer bij iedere afgeronde query of de recordlimiet is overschreden.
Vergelijk uitkomsten parallel. Laat een representatief onderzoek tijdelijk zowel met de bestaande cmdlet als met Graph lopen. Vergelijk niet alleen aantallen, maar ook velden, tijdzone, filtergedrag en de verwerking door het doelsysteem.
Plan de omschakeling ruim voor 15 oktober 2027. Zet de oude route pas uit na een acceptatietest, documenteer de terugvalprocedure voor de overgangsperiode en werk runbooks, dashboards en leveranciersafspraken bij.

Een veilig technisch basispatroon

Onderstaand patroon laat de volgorde zien, niet een volledig productiescript. Vul uitsluitend filters in die voor het onderzoek nodig zijn en behandel de toegangstoken- en foutafhandeling buiten de voorbeeldcode.

POST /v1.0/security/auditLog/queries
  - filterStartDateTime en filterEndDateTime
  - eventueel operation-, user- of recordtypefilters

GET  /v1.0/security/auditLog/queries/{query-id}
  - herhaal met back-off zolang de status niet terminal is
  - controleer na afloop isRecordCountLimitExceeded

GET  /v1.0/security/auditLog/queries/{query-id}/records
  - verwerk alle pagina's en leg een checkpoint vast

Gebruik geen blinde één-op-éénvertaling van PowerShell-parameters. De Graph-API heeft een eigen gegevensmodel en een eigen autorisatiemodel. Test daarom per use case, zeker wanneer een script een breed tijdsvenster of een groot aantal auditrecords verwerkt.

Tijdlijn en aandachtspunt voor beheerders

De AuditLogQuery-API is volgens Microsoft Message Center MC1505599 in oktober 2026 algemeen beschikbaar. De bestaande cmdlet blijft volgens dezelfde aankondiging werken tot en met 14 oktober 2027. Vanaf 15 oktober 2027 levert Search-UnifiedAuditLog geen toegang meer tot het auditlog. Wacht niet tot de laatste maanden: de meeste tijd gaat doorgaans zitten in eigenaarschap, toestemming, testdata en aanpassing van afhankelijke processen, niet in de eerste API-aanroep.