How to use Get-mguser in Powershell

Efficient user management inside Microsoft 365 environments is not always easy.

Some organizations have thousands of user accounts to manage, which can turn this task into a real challenge.

Fortunately, PowerShell integrates the Get-MgUser cmdlet, a command part of the Microsoft Graph PowerShell SDK, which provides an invaluable way to interact with user data in Microsoft 365.

Let's learn how to use Get-MgUser in PowerShell to start streamlining tasks, ranging from basic user queries to complex data retrieval and reporting.

What is the Get-MgUser Command?

Get-MgUser is a relatively new cmdlet used to retrieve and export Azure AD users, which is part of the Microsoft Graph PowerShell SDK.

Microsoft Graph is a gateway to data and intelligence in Microsoft 365, and the PowerShell SDK provides cmdlets to interact with it.

The Get-MgUser cmdlet is specifically used to retrieve information about users in a Microsoft 365 environment. It can be used to list all users, get detailed information about a specific user, or filter users based on certain criteria like department, job title, or other user attributes.

The syntax of the Get-MgUser command is the following:

Get-MgUser

[-ExpandProperty <String[]>]

[-Property <String[]>]

[-Filter <String>]

[-Search <String>]

[-Sort <String[]>]

[-Top <Int32>]

[-ConsistencyLevel <String>]

[-PageSize <Int32>]

[-All]

[-CountVariable <String>]

[<CommonParameters>]

To efficiently use this cmdlet, it's important to understand the meaning of each parameter:

  • ExpandProperty: This parameter allows you to specify related entities to include in the response. You can expand related records that would not otherwise be included in the returned object;
  • Property: This lets you specify which properties of the user object you want to retrieve. If not specified, the cmdlet returns a default set of user properties;
  • Filter: This parameter is used to filter the users returned. You can use it to specify criteria that the results must meet, such as filtering by job title, department, etc;
  • Search: This option allows you to perform a search query on the user data. It's used for more complex queries than what -Filter allows;
  • Sort: This parameter is used to sort the returned user objects by one or more properties;
  • Top: This parameter limits the number of results returned;
  • ConsistencyLevel: This option specifies the consistency level of the query. It's an advanced feature used in scenarios where data consistency is critical;
  • PageSize: This sets the page size for the results. It determines how many results are included in each page when the response is paginated;
  • All: This switch, when used, retrieves all users in the directory without the need to manually handle pagination;
  • CountVariable: This parameter stores the total count of objects found in a variable, even if you're only returning a subset of them.

What Can You Use Get-MgUser For?

The Get-MgUser cmdlet lists users as requested by the administrator, which brings the following benefits (among others):

  1. List All Users in Your Organization: You can use Get-MgUser to list all the users in your Microsoft 365 environment. This is particularly useful for administrators to get an overview of all users, including basic information like their names, user principal names, and job titles;
  2. Retrieve Detailed Information About a Specific User: By using the -UserId parameter or filtering options, you can fetch detailed information about a specific user. This includes their contact information, department, office location, manager details, and other attributes stored in the Microsoft 365 directory;
  3. Find Users Based on Specific Criteria: With the -Filter parameter, you can search for users based on specific criteria, such as department, location, or job title. For instance, you might want to list all users who work in a particular department or have a specific role within the organization.

Prerequisites to Use the Get-MgUser Command in PowerShell

Since the Get-MgUser command is a powerful cmdlet that returns a list of vital company information, users need to comply with a series of prerequisites before using it:

  • PowerShell Installation: Ensure that PowerShell is installed on your system. Get-MgUser works on the latest PowerShell version, as we are talking about a cmdlet introduced in late 2022;
  • Microsoft Graph PowerShell SDK: You need to have the Microsoft Graph PowerShell Module installed. You can install it using the PowerShell command: Install-Module Microsoft.Graph;
  • Appropriate Azure AD Permissions: The account or application used to connect to Microsoft Graph must have the necessary permissions to access user data. If you lack the required permissions, contact your organization administrator for further assistance.

How to Use Get-MgUser Command in PowerShell

To use the Get-MgUser command, we need to follow three quick steps.

Step 1: Connect to Exchange Online PowerShell

Start by connecting to Exchange Online PowerShell. Open the program on your computer and run the following prompt:

Connect-ExchangeOnline -UserPrincipalName youremail@meetingroom365.com

Use your Microsoft account credentials to sign in, and move on to the following step.

Step 2: Install the Microsoft Graph Module

Now, since the Get-MgUser command works in Microsoft Graph and Azure environments, it's important to install the correct module by running this command:

Install-Module Microsoft.Graph

Once the Microsoft Graph module has been installed on your system, run this prompt to connect to it:

Connect-MgGraph

Step 3: Run the Get-MgUser Command

We are now ready to run the cmdlet (provided that you have sufficient permissions), and there are a couple of options to do so.

The first one consists of getting a full list of all users within an organization:

Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -All | Format-List ID, DisplayName, Mail, UserPrincipalName

The aforementioned command will return a list of all users, including their display names, email addresses, and UPNs.

However, if you want to get more narrowed information, you may use the filter options like this:

Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -ConsistencyLevel eventual -Count userCount -Filter "startsWith(DisplayName, 'a')" -Top 1

The aforementioned command returns the top 1 users with the display name starting with the letter "a." The Consistency Level operator indicates that the command can tolerate eventual consistency for data, returning a more narrowed user list.

Why Can't I Use Get-MgUser? Common Errors & How to Fix Them

If you tried to use the Get-MgUser cmdlet, but the prompt is returning an error message, follow these Microsoft recommendations:

  • Install the Module: Use Install-Module Microsoft.Graph to correctly install the Microsoft Graph module. If the module hasn't been correctly installed, then the command won't work as expected;
  • Update the Installed Module: In some cases, it'll be necessary to use the Update-Module Microsoft.Graph in order to get the latest module version;
  • Authentication & Permissions Errors: Make sure you have sufficient permissions to run the command. Likewise, use the correct credentials when logging into Exchange Online PowerShell to prevent further error messages.

Wrapping Up: Using Get-GmUser in PowerShell

From basic functions like displaying a list of all users in your organization to more advanced actions like sorting users based on particular characteristics or handling multiple user accounts at once, Get-MgUser showcases the strength and flexibility of PowerShell for managing users in cloud environments.

Before using the command, make sure to install the correct Microsoft Graph module and have sufficient permissions. Otherwise, error messages will start to appear.