Get-MgUser: How to Get and Export Azure AD users with PowerShell

Starting from Dec 2022 we will need to use the Get MgUser cmdlet to get and export our Azure AD users. Get-MgUser is part of the Microsoft Graph SDK for PowerShell. It allows us to interact with all Microsoft Services through a single endpoint.

All the user accounts in your Microsoft 365 tenant are stored in the Azure Active Directory. We can manage them through the admin center or Azure Portal, but sometimes is PowerShell more convenient.

In this article, I am going to explain how we can use the Get MgUser cmdlet to find and retrieve user information from the Azure AD. I have also created a complete script that allows you to export all your users to CSV, which you will find at the end of the article.

Getting started with Get-MgUser

Before we can start, make sure that you have installed the Microsoft Graph Module in PowerShell. In this article, you can find a complete guide on how to install the module.

The Get MgUser cmdlet allows you to find and extract user information from the Azure Active Directory. There are a couple of parameters that we can use to find or filter the users:

• UserId – Return specific user based on UPN or ObjectID
• Filter – Retrieve multiple objects based on a oDate v3 query
• Search – Get all users that match the searchString
• Top – Return n number of results
• All – Return all results (by default the first 100 items are returned)

Good to know is the cmdlet returns only the first 100 results by default. So make sure that you use the -all parameter to get all results when needed.

So the first step is to connect the Microsoft Graph with the correct scope. We are only going to retrieve user data, so we can use the User.Read.All scope.

Connect-MgGraph -Scopes 'User.Read.All'

To test if the cmdlet is working you can simply get all users from your Azure Active Directory with the following cmdlet:

Get-MgUser -All

To get a single user we can use the UserId of the user. This can either be the UserPrincipalName of the user or the actual user id:

# Get the user by the UserPrincipalName
Get-MgUser -UserId [email protected]

# Get the user by the actual id:
Get-MgUser -UserId 7a3b301d-0462-41b6-8468-19a3837b8ad1

Using Filters with Get-MgUser

Just like with the Get-AzureAduser cmdlet we can filter the users. The filter is based on the oDate v3 query, but not all operators are supported. We can only use the following operators to filter to users:

Operator	Description	Example
eq	Equals to	jobtitle eq ‘Marketing Assistant’
and	And	jobtitle eq ‘Recruiter’ and jobtitle eq ‘hr’
or	Or	jobtitle eq ‘Recruiter’ or jobtitle eq ‘hr’
startswith	String starts with	startswith(jobtitle,’recr’)

Important is that you wrap the filter query in double-quotes and the string that you want to filter on in single-quotes. Only when you filter on a boolean you don’t need to put quotes around the true or false statement.

So let’s take a look at a couple of examples using the -filter parameter. To find a user by the display name we can specify the complete name of the user or use the startsWith operator. Keep in mind that we can’t use wildcard or the -like operator here.

# Find the user based on the full name
Get-MgUser -Filter "DisplayName eq 'Adele Vance'"

# Find the user by the first part of the name
Get-MgUser -Filter "startsWith(DisplayName, 'A')"

The same method can also be used to get all users with the job title “Marketing Assistant” for example:

Get-MgUser -Filter "jobtitle eq 'Marketing Assistant'"

To get for example only the enabled user accounts with the Get-MgUser cmdlet we can use the following command:

Get-MgUser -Filter 'accountEnabled eq true' -All

Note that I have added the -all parameter. By default, the Get MgUser cmdlet only returns the first 100 results. By adding the -all parameter we get all the results returned.

We can also filter on multiple conditions, by using and or or in the filter query:

Get-MgUser -Filter "department eq 'Marketing' and jobtitle eq 'Manager'"

Using Search to Find Users

Besides the filter parameter, we can also use the -Search parameter to find users. The parameter requires a property that you want to search on and a value. You will also need to set the -consistencylevel to eventual.

The advantage of the -search parameter is that it allows us to search on any part of the value. So for example, if want to search on a part of the name we can use :

Get-MgUser -Search 'DisplayName:van' -ConsistencyLevel eventual

Also, note that you will need to wrap the search query in single quotes. You can use the search parameter on pretty much all the fields that are returned by the Get-MgUser cmdlet.

Combining Search and Filter in Get MgUser

We can also combine the -search and -filter parameters in one command. This allows us to search on a name or job title among enabled accounts only for example:

Get-MgUser -Filter 'accountEnabled eq true' -Search 'DisplayName:van' -ConsistencyLevel eventual

Selecting Properties to Return

When using the Get-MgUser cmdlet you have probably noticed that it doesn’t return a lot of properties by default. Most fields are empty or contain the value Microsoft.Graph.PowerShell.Models. followed by an entity name. So how do we retrieve this data?

There are two parameters that we can use to get the information that we need, -property and -expandproperty.

The -property parameter is just like the select that we can pipe behind the cmdlet. The only difference is that with select, all data is returned by Microsoft Graph and filtered out in PowerShell.

Get-MgUser -UserId [email protected] | Select DisplayName,BusinessPhones,Mail,JobTitle

DisplayName BusinessPhone     Mail                           JobTitle
----------- -------------     ----                           --------
Adele Vance {+1 425 555 0109} [email protected] Retail Manager

When you use the property parameter, only the data that you need is returned by Microsoft Graph. Especially when working with a lot of records this will be faster than using select.

Get-MgUser -UserId [email protected] -Property DisplayName,BusinessPhones,Mail,JobTitle | fl

If you output the results to a list, you will see that only the fields that you have selected with the property parameter contain data.

Expanding Microsoft.Graph.PowerShell.Models

When viewing the properties of a user you may have noticed that some of them contain the value Microsoft.Graph.PowerShell.Models followed by a resource name. These models (or resources) are relationships of the resource type that you are viewing.

These relationships should allow us to easily view the related data of the resource. If we take the user, we may want to know the manager of it.

To do this we will need to expand the properties and select the correct parameter of the manager object:

Get-MgUser -UserId [email protected] -ExpandProperty manager | Select @{Name = 'Manager'; Expression = {$_.Manager.AdditionalProperties.displayName}}

# Result:
Manager
-------
Miriam Graham

The challenge with those relationships is to find the correct field and permissions that you need. We are now connected to Microsoft Graph with only the User.Read.All scope. If we for example want to view the working hours of a user in the mailbox settings, then we first need to find and add the correct scope to our session.

To find the correct permission I like to use the Rest API documentation. If you expand a resource it will show the relationships of the resource. You can then click on the type which will take you to the related resource where you can find the required permissions.

So for the mailbox settings, we will need to add the MailboxSettings.Read permissions:

Connect-MgGraph -Scopes "User.Read.All","MailboxSettings.Read"

And then we can select the property and nested values:

Get-MgUser -UserId r[email protected] -Property MailboxSettings | Select @{Name = 'days'; Expression = {$_.MailboxSettings.WorkingHours.DaysofWeek}}

Script to get all Azure AD Users and Export to CSV

I have created a complete script that allows you to get and export all Azure Active Directory users to a CSV file. There are a couple of options when you run the script:

• Get the manager of the user – Default True
• Get enabled, disabled or both user accounts – Default True
• Set the export path for the CSV file – By default the location of the script

You can download the latest version of the script here from my GitHub repository. To run the script, simply navigate to the script location and run:

.\Get-MgUsers.ps1 -path c:\temp\users.csv

If you want to know more on how to run a script, or how to add your script location to your PowerShell profile, then make sure that you read this article.

<#
.SYNOPSIS
  Get all Azure AD Users using Microsoft Graph with properties and export to CSV

.DESCRIPTION
  This script collects all Azure Active Directory users with the most important properties. By default it will only
  get the enabled users, manager of the user and searches the whole domain.

.OUTPUTS
  CSV with Azure Active Directory Users

.NOTES
  Version:        1.0
  Author:         R. Mens - LazyAdmin.nl
  Creation Date:  15 feb 2022
  Purpose/Change: Initial script development

.EXAMPLE
  Get all AzureAD users from the whole Domain

   .\Get-MgUsers.ps1 -path c:\temp\users.csv

.EXAMPLE
  Get enabled and disabled users

   .\Get-MgUsers.ps1 -enabled both -path c:\temp\users.csv

   Other options are : true or false

.EXAMPLE
  Don't lookup the managers display name
  .\Get-MgUsers -getManager:$false -path c:\temp\users.csv
#>


param(
  [Parameter(
    Mandatory = $false,
    HelpMessage = "Get the users manager"
  )]
  [switch]$getManager = $true,

  [Parameter(
    Mandatory = $false,
    HelpMessage = "Get accounts that are enabled, disabled or both"
  )]
    [ValidateSet("true", "false", "both")]
  [string]$enabled = "true",

  [Parameter(
    Mandatory = $false,
    HelpMessage = "Enter path to save the CSV file"
  )]
  [string]$path = ".\ADUsers-$((Get-Date -format "MMM-dd-yyyy").ToString()).csv"
)


Function Get-Users {
    <#
    .SYNOPSIS
      Get users from the requested DN
    #>
    process{
      # Set the properties to retrieve
      $properties = @(
        'id',
        'DisplayName',
        'userprincipalname',
        'mail',
        'jobtitle',
        'department',
        'OfficeLocation',
        'MobilePhone',
        'BusinessPhones',
        'streetAddress',
        'city',
        'postalcode',
        'state',
        'country',
        'AccountEnabled',
        'CreatedDateTime'
      )

      If (($getManager.IsPresent)) {
        # Adding additional properties for the manager
        $select = $properties += @{Name = 'Manager'; Expression = {$_.Manager.AdditionalProperties.displayName}}
        $select += @{Name ="Phone"; Expression = {$_.BusinessPhones}} 
      }else{
        $select = $properties
      }

      # Get enabled, disabled or both users
      switch ($enabled)
      {
        "true" {$filter = 'AccountEnabled eq true'}
        "false" {$filter = 'AccountEnabled eq false'}
        "both" {$filter = ''}
      }

      # Get the users
      Get-MgUser -Filter $filter -Property $properties -ExpandProperty Manager | select $select
    }
}


Function Get-AllMgUsers {
  <#
    .SYNOPSIS
      Get all AD users
  #>
  process {
    Write-Host "Collecting users" -ForegroundColor Cyan

    # Collect and loop through all users
    Get-Users | ForEach {

      [pscustomobject]@{
        "Name" = $_.DisplayName
        "UserPrincipalName" = $_.UserPrincipalName
        "Emailaddress" = $_.mail
        "Job title" = $_.JobTitle
        "Manager" = $_.Manager
        "Department" = $_.Department
        "Office" = $_.OfficeLocation
        "Phone" = $_.Phone
        "Mobile" = $_.MobilePhone
        "Enabled" = if ($_.AccountEnabled) {"enabled"} else {"disabled"}
        "Street" = $_.StreetAddress
        "City" = $_.City
        "Postal code" = $_.PostalCode
        "State" = $_.State
        "Country" = $_.Country
        "Account Created on" = $_.CreatedDateTime
      }
    }
  }
}

# Check if MS Graph module is installed
if (Get-InstalledModule Microsoft.Graph) {
  # Connect to MS Graph
  Connect-MgGraph -Scopes "User.Read.All"
}else{
  Write-Host "Microsoft Graph module not found - please install it" -ForegroundColor Black -BackgroundColor Yellow
  exit
}

Get-AllMgUsers | Sort-Object Name | Export-CSV -Path $path -NoTypeInformation

if ((Get-Item $path).Length -gt 0) {
  Write-Host "Report finished and saved in $path" -ForegroundColor Green

  # Open the CSV file
  Invoke-Item $path

}else{
  Write-Host "Failed to create report" -ForegroundColor Red
}

Wrapping Up

The Microsoft Graph SDK for PowerShell is still pretty new and not well documented at the moment of writing. So it can be a bit of a challenge to find the correct syntax or cmdlet to get the information that you need.

I hope this article helped you to get started with the Get MgUser cmdlet. If you have any questions just let me know in the comments below.