Track M365 Admin Role Assignments Using Graph PowerShell

In large organizations, tracking admin role assignments in Azure AD is critical for security and auditing purposes. Azure AD provides several administrative roles that can be granted to users, and monitoring when and by whom these roles are assigned is crucial to maintaining a secure environment. In this article, we’ll walk through a simple PowerShell script that utilizes Microsoft Graph PowerShell to track users who were recently assigned admin roles. This script can be an essential tool in your auditing toolkit.

The Script

# Define the time range for recent role changes (e.g. past 7 days)
$startDate = (Get-Date).AddDays(-7).ToString("yyyy-MM-ddTHH:mm:ssZ")

# Fetch audit logs for directory role assignments in the given time range
$logs = Get-MgAuditLogDirectoryAudit -Filter "activityDateTime ge $startDate and activityDisplayName eq 'Add member to role'" -All

# Initialize an array to store the results
$results = @()

# Loop through the audit logs and extract the required information
foreach ($log in $logs) {
    $roleAddedTime = $log.ActivityDateTime
    $roleAddedTo = $log.TargetResources | Where-Object { $_.Type -eq 'User' } | Select-Object -ExpandProperty UserPrincipalName
    $addedBy = $log.InitiatedBy.User.UserPrincipalName

    # Create a custom object to store the data
    $result = [pscustomobject]@{
        "Added Time"      = $roleAddedTime
        "Role Added To"   = $roleAddedTo
        "Added By"        = $addedBy
    }

    # Add the result to the results array
    $results += $result
}

# Display the results in a table format
$results | Format-Table -AutoSize

How the Script Works

• Time Range: The script starts by defining a time range for the role assignments you want to track (the last 7 days in this case). You can modify the date range to suit your needs.
• Audit Log Retrieval: The Get-MgAuditLogDirectoryAudit cmdlet is used to query Azure AD for audit logs that show "Add member to role" events. These logs contain details of users who were assigned new roles within the specified time frame.
• Data Extraction: For each log entry, the script extracts the role assignment time (ActivityDateTime), the user assigned the role (UserPrincipalName), and the admin who made the assignment (InitiatedBy.User.UserPrincipalName).
• Output: The results are displayed in a neatly formatted table showing the time of the role assignment, the user who received the role, and the admin who performed the action.

Further Enhancing the Script

• Role Information: You can extend the script to extract and display the role name by querying the ModifiedProperties field within each log.
• Custom Date Range: Modify the script to accept user input for the date range, allowing administrators to track role assignments over any custom period.
• Exporting Results: Instead of just displaying the results, you can export them to a CSV file for reporting purposes by replacing the Format-Table line with:

$results | Export-Csv -Path "C:\AdminRoleAssignments.csv" -NoTypeInformation

Frequently Asked Questions

• How often should I review admin role assignments?

It’s best practice to review assignments at least once a month. Frequent audits help identify unauthorized privilege escalation or temporary role assignments that were never revoked.

• Can I filter audit logs for specific roles, like Global Administrator?

Yes. Use the -Filter parameter with role display names or look into the ModifiedProperties field of audit logs to isolate changes related to a particular role, such as Global Administrator.

• How long are audit logs retained in Microsoft 365?

Audit log retention depends on your license. Microsoft 365 E3 typically retains logs for 90 days, while E5 or add-on licenses extend retention up to a year or more. Make sure your script timeframe aligns with your organization’s retention policy.

• What should I do if the logs don’t return expected results?

First, confirm that audit logging is enabled in your tenant. Next, check your date range and parameters. If results are still missing, ensure your account has appropriate permissions (like AuditLog.Read.All) to query directory audit logs.

Possible Errors and Solutions

Error	Cause	Solution
Permission Issues	Ensure that the account running this script has appropriate permissions to read Azure AD audit logs.	Typically, the account should have the AuditLog.Read.All permission in Microsoft Graph.
Audit Log Retrieval Issues	If the Get-MgAuditLogDirectoryAudit cmdlet returns an empty result or throws an error, verify that auditing is enabled in your Azure AD tenant.	If auditing is not turned on, you will not be able to retrieve log entries.
Throttling	If the audit log query is large, you might encounter throttling from Microsoft Graph.	In such cases, reduce the date range or implement paging in the query using -Top and -Skip parameters.

Conclusion

This script provides a simple but effective way to monitor recent admin role assignments in your Azure AD environment. Keeping track of admin role assignments is essential to ensure that proper security measures are in place and to quickly identify any unexpected or unauthorized changes. As your auditing needs grow, this script can easily be enhanced to include more data such as role names or exporting the results for reporting purposes. Regularly monitoring admin role assignments will help maintain a secure and well-managed Azure AD environment.