M365 PowerShell

View Licensed and Unlicensed Microsoft 365 Users with Graph PowerShell

Managing user licenses in Microsoft 365 is crucial for ensuring that resources are allocated efficiently and that users have access to the services they need. In this article, we will explore a Graph PowerShell script that lists both licensed and unlicensed users in a table format. We will delve into how the script works, how it can be enhanced, and discuss potential errors and solutions.

The Script

Below is the Graph PowerShell script that lists licensed and unlicensed users separately:

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Read.All"

# Retrieve all users and their assigned licenses
$allUsers = Get-MgUser -All -Property "Id,DisplayName,UserPrincipalName,AssignedLicenses"

# Filter licensed and unlicensed users
$licensedUsers = $allUsers | Where-Object { $_.AssignedLicenses.Count -gt 0 }
$unlicensedUsers = $allUsers | Where-Object { $_.AssignedLicenses.Count -eq 0 }

# Display licensed users in a table format
Write-Host "Licensed Users:"
$licensedUsers | Select-Object DisplayName, UserPrincipalName, ID | Format-Table -AutoSize

# Display unlicensed users in a table format
Write-Host "`nUnlicensed Users:"
$unlicensedUsers | Select-Object DisplayName, UserPrincipalName, ID | Format-Table -AutoSize

How the Script Works

Connect to Microsoft Graph: The Connect-MgGraph cmdlet establishes a connection to Microsoft Graph with the necessary permissions (User.Read.All).
Retrieve Users: The Get-MgUser cmdlet fetches all users and includes the properties Id, DisplayName, UserPrincipalName, and AssignedLicenses.
Filter Users: Using the Where-Object cmdlet, the script filters users into two categories: those with assigned licenses ($licensedUsers) and those without ($unlicensedUsers).
Display Users: The Select-Object and Format-Table cmdlets format and display the licensed and unlicensed users in a table format for easy readability.

Script Output:

Note:: You can look for a specific user's license details by running Get-MgUserLicenseDetail -UserId <UPN>

Enhancing the Script

The script can be enhanced in various ways to provide more functionality and flexibility:

Include Additional User Information: Display additional information such as department.

$licensedUsers | Select-Object DisplayName, UserPrincipalName, Department | Format-Table -AutoSize
$unlicensedUsers | Select-Object DisplayName, UserPrincipalName, Department | Format-Table -AutoSize

Export Results to a CSV File: Export the list of licensed and unlicensed users to a CSV file for easier analysis and record-keeping.

# Export licensed users to CSV
$licensedUsers | Select-Object DisplayName, UserPrincipalName | Export-Csv -Path "LicensedUsers.csv" -NoTypeInformation

# Export unlicensed users to CSV
$unlicensedUsers | Select-Object DisplayName, UserPrincipalName | Export-Csv -Path "UnlicensedUsers.csv" -NoTypeInformation

Add Error Handling: Implement error handling to manage potential issues during script execution.

try {
    Connect-MgGraph -Scopes "User.Read.All"
}
catch {
    Write-Host "Failed to connect to Microsoft Graph. Please check your credentials and permissions." -ForegroundColor Red
    exit
}

try {
    $allUsers = Get-MgUser -All -Property "Id,DisplayName,UserPrincipalName,AssignedLicenses"
}
catch {
    Write-Host "Failed to retrieve users. Please check your network connection and permissions." -ForegroundColor Red
    exit
}

Possible Errors & Solutions

Error	Solution
Authentication failed. Please check your credentials.	Ensure that the account used has the necessary permissions (User.Read.All) and that multi-factor authentication (MFA) is properly configured.
Insufficient privileges to complete the operation.	Verify that the account has the required permissions. You may need to grant additional permissions or use an account with higher privileges.
Failed to connect to Microsoft Graph	Check your internet connection and ensure that your firewall or proxy settings are not blocking the connection to Microsoft Graph.

Frequently Asked Questions

Do I need to use -ConsistencyLevel eventual when filtering licensed or unlicensed users?
Not necessarily. If you're using Where-Object for local filtering after retrieving all users, you don’t need it. However, if you plan to use server-side filtering with the -Filter parameter on assignedLicenses, then -ConsistencyLevel eventual and -CountVariable are required.
Why do some guest accounts appear as unlicensed?
Guest accounts usually don’t require licenses unless explicitly assigned. It’s common to find many guest users marked as unlicensed — these often have restricted access depending on organization settings.

How can I export the licensed and unlicensed user lists to a CSV file?
You can pipe the results into Export-Csv. For example:

$licensed | Export-Csv -Path "LicensedUsers.csv" -NoTypeInformation  
$unlicensed | Export-Csv -Path "UnlicensedUsers.csv" -NoTypeInformation

✅ Prefer Server-Side Filtering for Large Tenants

Using Where-Object works well for smaller environments.
But for larger tenants, fetching all users and filtering locally can be inefficient.
For better performance, consider using the -Filter parameter with assignedLicenses/$count (and -ConsistencyLevel eventual) to perform filtering on the server side.

✅ Identify License-Skipped Guest Accounts

Guest users often appear as unlicensed but may not require licenses.
To avoid confusion, filter only member-type users when auditing license assignments.
This keeps your reports clean and focused on licensable accounts.

Conclusion

This Graph PowerShell script provides a simple yet effective way to list licensed and unlicensed users in Microsoft 365. By understanding how the script works and exploring ways to enhance it, you can tailor it to better fit your organization’s needs. Additionally, being aware of potential errors and their solutions can help you troubleshoot issues effectively, ensuring smooth operation.

With this script, administrators can gain valuable insights into their licensing status, helping to optimize resource allocation and ensure compliance with licensing requirements.

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell