PowerShell

Using Get-MgAuditLogDirectoryAudit with Get-MgUser: Monitor Group Membership Changes and Audit User Activities

In Microsoft 365, monitoring changes to group memberships is vital for maintaining security and compliance. Whether it's tracking who added or removed users from groups, or auditing specific user actions, the combination of Get-MgUser and Get-MgAuditLogDirectoryAudit cmdlets enables administrators to efficiently monitor and audit directory activities. This article walks you through a practical example of using these cmdlets together to monitor group membership changes initiated by a specific user.

Usage Example: Monitor Group Membership Changes

The following script retrieves group membership changes (additions or removals) made by a specific user within the past 7 days:


# Specify the user for whom you want to monitor group membership changes
$userPrincipalName = "john.doe@yourdomain.com"

# Retrieve the user's Object ID using Get-MgUser
$userId = (Get-MgUser -UserId $userPrincipalName -Property "id").Id

# Set the date range for the audit logs (Last 7 days)
$startDate = (Get-Date).AddDays(-7).ToString("yyyy-MM-ddTHH:mm:ssZ")
$endDate = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ssZ")

# Retrieve directory audit logs for group membership changes
$auditLogs = Get-MgAuditLogDirectoryAudit -Filter "initiatedBy/user/id eq '$userId' and (activityDisplayName eq 'Add member to group' or activityDisplayName eq 'Remove member from group') and activityDateTime ge $startDate and activityDateTime le $endDate"

# Format and display the audit logs
$auditLogs | Select-Object Id, ActivityDisplayName, TargetResources, LoggedByService, ActivityDateTime

Use Cases

Monitor Group Membership Changes by Specific Users: Track when a user adds or removes members from groups to ensure changes are authorized and align with organizational policies.
Audit Compliance: Generate reports of user-initiated actions on sensitive groups, such as those containing administrators or security-critical roles, to meet compliance requirements.
Investigate Unauthorized Activities: Identify potentially malicious or accidental changes to group memberships by auditing user actions within a specified timeframe.
Generate Reports for Security Reviews: Export detailed logs of group membership activities for periodic security reviews or internal audits.

Tips and Best Practices

Define a Reasonable Time Range: Always use a date range (activityDateTime ge and activityDateTime le) to narrow down results and avoid overloading the query.
Use Meaningful Filters: Tailor the -Filter parameter to include only relevant activities such as Add member to group or Remove member from group to focus on group membership changes.
Export Logs for Analysis: Use the Export-Csv cmdlet to save logs for further analysis or reporting:
```
$auditLogs | Export-Csv -Path "GroupMembershipChanges.csv" -NoTypeInformation
```
Include Error Handling: Add error handling to gracefully manage scenarios where no logs are available or user actions are not found:
```
if (-not $auditLogs) {
    Write-Host "No audit logs found for the specified criteria."
}
```
Limit Permissions: Ensure the account running the script has only the necessary permissions, such as AuditLog.Read.All and User.Read.All, to minimize security risks.

Possible Errors & Solutions

Error	Cause	Solution
Insufficient privileges to complete the operation.	Missing permissions like `AuditLog.Read.All`.	Grant the required permissions to the account or app in Azure AD.
Invalid filter clause.	Syntax error in the `-Filter` parameter.	Verify the filter syntax and ensure properties like `initiatedBy/user/id` and `activityDisplayName` are correct.
No audit logs found for the specified criteria.	The user did not perform any relevant actions during the specified time period.	Expand the date range or refine the filter to capture additional activities.

🔍 Correlate Audit Entries with Users Using targetResources

Each audit log entry contains a targetResources array, where you can find fields like userPrincipalName or Id of the affected object.

Combine this with Get-MgUser to fetch additional details about the user involved in the action.

⏳ Use activityDateTime for Date Filtering — Not startDateTime

To filter audit records by date, use the activityDateTime property.

Fields like startDateTime or endDateTime are not supported in OData queries and will return a 400 Bad Request error.

Conclusion

Using Get-MgUser with Get-MgAuditLogDirectoryAudit empowers administrators to monitor and audit group membership changes efficiently. By combining these cmdlets, you can track user-initiated changes, generate compliance reports, and enhance your organization's security posture. Start implementing this script today to streamline your monitoring and auditing workflows.