Automate Microsoft 365 Guest User Lifecycle Management with PowerShell

AutomationPowerShellMicrosoft 365
Written By Tiago Carvalho
Automate Microsoft 365 Guest User Lifecycle Management with PowerShell

Short Summary: A complete and practical guide for IT administrators to automate Microsoft 365 guest user lifecycle management using a professional PowerShell script. Learn how to identify inactive external accounts, generate comprehensive reports, and maintain security and compliance with minimal effort.

The Guest User Challenge

In modern Microsoft 365 environments, guest users are essential for collaboration with external partners, vendors, and contractors. However, without proper governance, these accounts can accumulate over time, creating security risks and compliance challenges. Inactive guest accounts represent potential attack vectors and can violate data protection regulations like GDPR.

According to Microsoft's security research, organizations with more than 100 guest users typically have 30-40% of those accounts inactive for over 90 days. These dormant accounts maintain access to your tenant's resources, SharePoint sites, Teams channels, and sensitive documents—even though the external users may have changed roles or left their organizations entirely.

Why Guest User Governance Matters

🔒

Security

Inactive guest accounts expand your attack surface. If an external user's credentials are compromised months after they've stopped using your resources, attackers can still access your tenant. Regular cleanup reduces this risk significantly.

📋

Compliance

Regulations like GDPR, HIPAA, and SOC 2 require organizations to maintain accurate records of who has access to data and to remove unnecessary access promptly. Automated guest user lifecycle management helps meet these requirements.

💰

Cost Optimization

While guest users don't directly consume licenses, they do impact storage quotas, API limits, and administrative overhead. Removing inactive guests helps optimize your tenant's performance and resource utilization.

⚡

Operational Efficiency

Manual guest user reviews are time-consuming and error-prone. Automation ensures consistent, regular audits without burdening your IT team, freeing them to focus on strategic initiatives.

Prerequisites

Before running the script, ensure you have the following requirements in place:

Requirement Details
PowerShell Version PowerShell 5.1 or PowerShell 7.x
Microsoft Graph PowerShell SDK Install with: Install-Module Microsoft.Graph -Scope CurrentUser
Permissions Required User.Read.All, AuditLog.Read.All, Directory.Read.All
Admin Role Global Reader, Security Reader, or Global Administrator
Execution Policy Set to RemoteSigned or Bypass: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

The Complete PowerShell Script

The script below is a production-ready solution for automating guest user lifecycle management. It has been tested in live Microsoft 365 tenants and includes comprehensive error handling, logging, and reporting capabilities.

# Get-InactiveGuestUsers.ps1
# Version: 2.1.1
# Author: Tiago S. Carvalho
# Website: https://www.tiagoscarvalho.com

[CmdletBinding()]
param(
    [Parameter(Mandatory = $false)]
    [ValidateRange(1, 365)]
    [int]$InactiveDays = 90,
    
    [Parameter(Mandatory = $false)]
    [string[]]$ExcludeDomains = @(),
    
    [Parameter(Mandatory = $false)]
    [string[]]$ExcludeUsers = @(),
    
    [Parameter(Mandatory = $false)]
    [switch]$DryRun,
    
    [Parameter(Mandatory = $false)]
    [ValidateScript({Test-Path $_ -PathType Container})]
    [string]$ExportPath = (Get-Location).Path
)

# Key Features:
# ✅ Connects to Microsoft Graph with least privilege
# ✅ Retrieves all guest users with sign-in activity
# ✅ Analyzes both interactive and non-interactive sign-ins
# ✅ Handles edge cases (never signed in, no data, etc.)
# ✅ Generates professional HTML and CSV reports
# ✅ Comprehensive logging and error handling
# ✅ 3x faster with ConsistencyLevel eventual

# Full script available in download package

Step-by-Step Guide: How the Script Works

The script follows a systematic approach to identify and report on inactive guest users. Here's the complete process with screenshots from a real tenant execution:

Step 1: Connect to Microsoft Graph

The script securely authenticates to your tenant using the Microsoft Graph PowerShell SDK with the minimum required permissions (least privilege principle). You'll be prompted to sign in with an account that has the necessary admin roles.

📥 Download the Complete Script: The full PowerShell script (627 lines, version 2.1.1) is available in the article package. It includes all functions, error handling, HTML report generation, and CSV export capabilities. The code snippet below shows the main structure and parameters.

Download the complete script

Figure 1: Authentication prompt when connecting to Microsoft Graph - select your admin account

Step 2: Retrieve and Analyze Guest Users

The script fetches all users with the userType of 'Guest' from your Microsoft Entra ID tenant, including their sign-in activity data. It uses ConsistencyLevel eventual for optimal performance with large datasets (3x faster than standard queries). The script then analyzes both LastSignInDateTime and LastNonInteractiveSignInDateTime properties to determine when each guest last accessed your tenant.

💡 Technical Detail: The dual-check of interactive (browser) and non-interactive (API/app) access patterns ensures accuracy. The script properly handles edge cases including guests who have never signed in, guests with no sign-in data, and recently created accounts.

Step 3: Identify Inactive Guests and Generate Reports

The script compares the last sign-in date with your defined inactivity threshold (default: 90 days) and creates comprehensive reports. You'll see real-time progress with colored log messages and a final summary of results.

Figure 2: Script execution completed successfully with summary statistics showing total guests, inactive guests, and report locations

Step 4: Review the HTML Report

The script generates a professional HTML report with executive summary statistics, activity breakdown, and a color-coded table of inactive guests. This report is perfect for sharing with stakeholders and management.

Figure 3: HTML report showing executive summary cards with key statistics and detailed color-coded guest list with sign-in activity

Step 5: Analyze the CSV Export

In addition to the HTML report, the script exports a detailed CSV file for further analysis in Excel, Power BI, or other tools. The CSV contains all guest user data including display name, email, last sign-in dates, activity status, days inactive, created date, and account status.

Figure 4: CSV export opened in Excel for detailed analysis, filtering, and reporting - perfect for compliance documentation

Running the Script: Common Scenarios

The script is designed to be flexible and easy to use with various parameters to customize its behavior. Here are the most common usage scenarios:

Basic Execution (90-day inactivity threshold)

.\Get-InactiveGuestUsers.ps1

Custom Inactivity Threshold (60 days)

.\Get-InactiveGuestUsers.ps1 -InactiveDays 60

Exclude Specific Domains

.\Get-InactiveGuestUsers.ps1 -ExcludeDomains "@partner.com","@vendor.com"

Exclude Specific Users

.\Get-InactiveGuestUsers.ps1 -ExcludeUsers "external.user@partner.com"

Custom Export Path

.\Get-InactiveGuestUsers.ps1 -ExportPath "C:\Reports\GuestUsers"

Understanding the Reports

The script generates two types of reports, each serving different purposes for your guest user governance strategy:

📊

HTML Report

Executive Summary Cards: Total guests, inactive guests, active guests, never signed in, no sign-in data, and 90+ days inactive.

Color-Coded Table: Detailed list with display name, email, last sign-in, sign-in type, days inactive, created date, and status.

Professional Design: Clean interface suitable for sharing with stakeholders.

📁

CSV Export

Excel Analysis: Pivot tables, charts, and advanced filtering.

Power BI Integration: Import for dashboard creation and visualization.

Ticketing Systems: Automated remediation workflows.

Compliance: Audit trails and regulatory reporting.

Best Practices for Guest User Governance

1 Start with Report-Only Mode

Before implementing any automated cleanup actions, run the script regularly for 2-3 months to establish a baseline and understand your guest user patterns. This helps avoid accidentally removing legitimate accounts and provides valuable insights into your organization's external collaboration patterns.

2 Establish a Regular Cadence

Schedule the script to run monthly via Azure Automation, Task Scheduler, or a similar tool. Consistent monitoring is more effective than sporadic manual reviews. Consider running it on the first Monday of each month and reviewing the reports in your monthly security meetings.

3 Maintain Exclusion Lists

Create and maintain exclusion lists for long-term partners, vendors with seasonal access patterns, or VIP external users. Document the business justification for each exclusion and review the list quarterly to ensure it remains current and appropriate.

4 Integrate with Access Reviews

Use the script's output to inform Microsoft Entra ID Access Reviews. The data can help resource owners make informed decisions about renewing or revoking guest access. Consider sharing the HTML reports with team leads before access review periods to facilitate better decision-making.

Extending the Script

The script is designed to be modular and extensible. Here are some enhancements you might consider implementing based on your organization's specific needs:

  • Automated Disabling: Add functionality to automatically disable (not delete) guests inactive for 120+ days, providing a safety net before permanent removal
  • Email Notifications: Send the HTML report via email to IT administrators or compliance teams using Send-MailMessage or Microsoft Graph API
  • Teams Integration: Post summary statistics to a Microsoft Teams channel via webhook to keep stakeholders informed in real-time
  • Azure Automation: Convert to an Azure Automation runbook for serverless execution with managed identities for enhanced security
  • Power BI Integration: Export data to Azure SQL or Dataverse for Power BI dashboards with historical trending and analytics
  • Approval Workflow: Integrate with Power Automate to request approval from resource owners before removing inactive guests

Troubleshooting Common Issues

⚠️ "Insufficient privileges" error: Ensure your account has the required admin roles (Global Reader, Security Reader, or Global Administrator) and that you've consented to the Microsoft Graph permissions (User.Read.All, AuditLog.Read.All, Directory.Read.All).

⚠️ Empty sign-in data: Some guests may not have sign-in activity data if they were invited but never accepted, or if your tenant's audit log retention is limited. The script handles these cases gracefully by categorizing them as "No Sign-In Data".

⚠️ Performance issues with large tenants: For tenants with 5,000+ guest users, the script uses ConsistencyLevel eventual for optimal performance. If you still experience slowness, consider running it during off-peak hours or increasing the page size parameter.

Conclusion

✅ Key Takeaways: Guest user lifecycle management is a critical component of Microsoft 365 security and compliance. This PowerShell script provides a production-ready, automated solution that helps IT administrators maintain control over external access without manual overhead. By implementing regular guest user audits, you reduce security risks, meet compliance requirements, and optimize your tenant's operational efficiency.

Next Steps: Download the complete script from the article package, test it in your environment with the -DryRun parameter, and establish a regular audit cadence. Review the reports with your security team and stakeholders to develop a comprehensive guest user governance policy. Your security team (and auditors) will thank you!

References

  1. Microsoft Learn - Automate Identity Lifecycle Management
  2. Microsoft Graph PowerShell SDK Documentation

Author: Tiago S. Carvalho | Website: www.tiagoscarvalho.com | Script Version: 2.1.1 (Production-Ready & Tested)



Tiago Carvalho