Entra ID Guest Accounts: Identify, Analyze, and Clean Up
For a while, I had been manually running cmdlets to export guest account reports from Entra ID. These reports were crucial for analyzing and cleaning up inactive accounts, but I often found myself retyping or searching for the right commands. To simplify the process, I created a straightforward PowerShell script to generate a CSV report of guest accounts.
Regularly reviewing guest accounts is important, especially if you’re not using advanced features like Entitlement Management in Entra ID. Identifying and removing inactive accounts helps keep your environment clean and secure.
The goal was to make the task easier:
Quickly export guest accounts to a CSV for further analysis.
Use bulk delete actions in Entra ID to remove stale accounts.
I primarily focus on analyzing environments and providing recommendations, so I didn’t include any code for deleting guest accounts. I don’t have or need deletion rights, and I wanted to keep the script safe and read-only. However, it’s flexible enough for others to modify if needed.
The Script
You can find the complete script in my GitHub repository. Feel free to download, review, or contribute improvements:
Before you run the script, you must install the Microsoft Entra PowerShell module
How the Script Works
The script starts by establishing a connection to Entra ID using the Connect-Entra cmdlet. A mandatory TenantId parameter is required, and the connection is made with the User.Read.All scope. This ensures that the script can access the necessary user information:
Connect-Entra -Scopes 'User.Read.All' -TenantId $TenantId
Retrieving and Filtering Guest Accounts
Next, the script retrieves all guest accounts and excludes any users that are synchronized from on-premises directories (DirSyncEnabled), ensuring you only work with accounts created directly in Entra ID. Additionally, there's an optional switch to filter out guests by their externalUserState, so you can focus on those still pending acceptance:
$guests = Get-EntraUser -Filter "userType eq 'Guest'" -All |
Select-Object DisplayName, UserPrincipalName, createdDateTime, signInActivity, externalUserState, DirSyncEnabled
# Exclude DirSyncEnabled guests.
$guests = $guests | Where-Object { $_.DirSyncEnabled -ne $true }
# Optionally filter to only include guests with a "PendingAcceptance" status.
if ($PendingAcceptanceOnly) {
$guests = $guests | Where-Object { $_.externalUserState -eq "PendingAcceptance" }
}
Building a Dynamic CSV File Name
The script then fetches the tenant’s display name and creates a dynamic CSV file name that includes the tenant name and the current date (formatted as YYYYMMDD). This helps keep your reports organized and easily identifiable:
$exportDate = Get-Date -Format "yyyyMMdd"
$tenantName = (Get-EntraTenantDetail).DisplayName
$csvPath = "C:\temp\$tenantName" + "_Guests_Report_" + "$exportDate.csv"
Exporting the Data to CSV
The filtered guest data is then formatted and exported to a CSV file. The report includes key properties such as UserPrincipalName, externalUserState, createdDateTime, and a calculated field for the last successful sign-in:
$guests |
Select-Object UserPrincipalName,
externalUserState,
createdDateTime,
@{Name = 'LastSuccessfulSignIn'; Expression = { $_.signInActivity.lastSuccessfulSignInDateTime }} |
Sort-Object -Property LastSuccessfulSignIn -Descending |
Export-Csv -Path $csvPath -NoTypeInformation -Delimiter ";"
Confirming the Export
Finally, the script outputs the file path to confirm that the report has been successfully exported:
Write-Output "Report exported to: $csvPath"
How to Use the Script
Save the Script
Save the complete script as Export-EntraGuestReport.ps1 in your preferred location.
Run the Script with Parameters
Open PowerShell and navigate to the script’s directory. Run the script using the following syntax, providing your TenantId as well as the optional switch if you want to filter for pending acceptance only:
.\Export-EntraGuestReport.ps1 -TenantId "your-tenant-ID" -PendingAcceptanceOnly
-TenantId: Mandatory. Replace "your-tenant-id" with your actual TenantId.
-PendingAcceptanceOnly: Optional. Include this switch to filter the report to only show guest accounts with a PendingAcceptance state.
Review the CSV Report
The script will export the CSV report to C:\temp\, with a file name that includes your tenant name and the current date. You can then open this file in Excel or any CSV reader for further analysis.
Conclusion
This script makes it easy to generate a report on guest accounts from Entra ID. It simplifies data extraction for analysis and cleanup, and its flexible design lets you adapt or expand it as needed.