Audit Invited Guest Users Using Graph PowerShell – Track External Invitations

As Microsoft 365 administrators, it’s crucial to monitor and audit who has been invited into your tenant—especially guest users. In this article, we’ll walk through a Graph PowerShell script that retrieves audit logs specifically for guest invitations and displays the relevant details. This script leverages Microsoft Graph Directory Audit logs under the UserManagement category.

Script: Track Guest User Invitations from Audit Logs

# Connect to Microsoft Graph with necessary scopes
Connect-MgGraph -Scopes "AuditLog.Read.All", "User.Read.All", "Directory.Read.All"
                                
# Set time range (last 28 days, as per standard audit log retention)
$startDateTime = (Get-Date).AddDays(-28).ToString("yyyy-MM-ddTHH:mm:ssZ")
$endDateTime = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ssZ")
                                
# Fetch 'Invite external user' audit logs from UserManagement category
$logs = Get-MgAuditLogDirectoryAudit -Filter "category eq 'UserManagement' and activityDisplayName eq 'Invite external user' and activityDateTime ge $startDateTime and activityDateTime le $endDateTime" -All
                                
# Prepare output array
$results = @()
                                
foreach ($log in $logs) {
    foreach ($target in $log.TargetResources) {
        # Check if the target is a guest user
        if ($target.UserPrincipalName -like "*#EXT#*" -or $target.UserPrincipalName -like "*@*") {
            $results += [PSCustomObject]@{
                "Display Name"     = $target.DisplayName
                "UPN"              = $target.UserPrincipalName
                "Sign In Status"   = "Invited"
                "Created Date/Time"= $log.ActivityDateTime
            }
        }
    }
}
                                
# Output in table format
$results | Format-Table -AutoSize
                            

How the Script Works

• Authentication: Uses Connect-MgGraph with the required scopes to access audit logs and directory information.
• Timeframe: Limits the query to the last 28 days, which aligns with the default retention period for audit logs in most Microsoft 365 editions.
• Filtering: Applies a server-side OData filter to retrieve only the audit events where the ActivityDisplayName is "Invite external user" under the "UserManagement" category.
• Processing:
• Iterates through each audit log entry and targets users with guest-like UPNs.
• Creates a custom object with the user’s Display Name, UPN, an "Invited" status (since we’re logging invitations, not actual sign-ins), and the timestamp when the action was logged.

Further Enhancements

To make this script more robust or tailored to your organization’s needs, consider:

• Add Export Functionality

$results | Export-Csv -Path "GuestUserInvitations_AuditReport.csv" -NoTypeInformation -Encoding UTF8

• Track Sign-In Status

Use Get-MgAuditLogSignIn to check if invited guests actually signed in:

Get-MgAuditLogSignIn -Filter "userPrincipalName eq 'guestuser@example.com'"

• Filter Unused Invitations

Build logic to compare invite date with actual sign-in to flag unused guest accounts.

Possible Errors & Solutions

Error	Cause	Solution
Get-MgAuditLogDirectoryAudit : Access is denied.	Insufficient permissions	Use Connect-MgGraph -Scopes "AuditLog.Read.All" and ensure the account has AuditLog Reader role.
The term 'and' is not recognized...	Prompt text or extra characters mistakenly copied into PowerShell	Only paste the code, not the instruction text or headers.
UserPrincipalName is null	Some guest entries might not have UPN	Add a condition to skip entries with null UPNs.

Use Cases

• Security Audits: Track external sharing and collaboration activities.
• Governance: Validate whether invited guests were needed and used.
• Compliance Reviews: Maintain documentation of external access for audits.
• Housekeeping: Identify stale guest accounts that never signed in.

Conclusion

This Graph PowerShell script provides a simple yet powerful audit mechanism for tracking guest user invitations into your Microsoft 365 environment. With minor tweaks, it can serve as a foundation for more advanced reporting, automation, and compliance workflows. Whether you're a solo admin or part of a security team, auditing external access should always be a part of your routine—and this script gets you there quickly.