Using -Search with Get-MgUser Cmdlet

The Get-MgUser cmdlet in Microsoft Graph PowerShell enables administrators to retrieve user details from Microsoft 365. The -Search parameter is a powerful feature that allows users to perform text-based searches on specific user properties. This article explores how to use -Search effectively with Get-MgUser, including practical examples to simplify user management.

Get-MgUser -Search Examples

Below are some commonly used search queries with Get-MgUser:

Search By Display Name

Get-MgUser -All -Search "displayName:John" -ConsistencyLevel eventual

Explanation:

• Retrieves all users whose display name contains "John".
• Example: Matches users like "John Doe" or "Johnny Appleseed".

Search By Mail Address

Get-MgUser -All -Search "mail:johnysins@7xh7fj.onmicrosoft.com" -ConsistencyLevel eventual

Explanation:

• Retrieves a user with the exact mail address johnysins@7xh7fj.onmicrosoft.com.

Search By User Principal Name (UPN)

Get-MgUser -All -Search "userPrincipalName:timjohnson@7xh7fj.onmicrosoft.com" -ConsistencyLevel eventual

Explanation:

• Retrieves a user whose User Principal Name (UPN) is timjohnson@7xh7fj.onmicrosoft.com.

Search By First Name (Given Name)

Get-MgUser -All -Search "givenName:John" -ConsistencyLevel eventual

Explanation:

• Retrieves users whose first name (GivenName) contains "John".
• Example: Matches users like "John Wick" or "John Carter".

Search By Last Name (Surname)

Get-MgUser -All -Search "surname:Singh" -ConsistencyLevel eventual

Explanation

• Retrieves users whose last name (Surname) contains "Singh".
• Example: Matches users like "Aman Singh" or "Raj Singh".

Important Considerations

1. Limited Filterable Properties: The -Search parameter only works with specific properties:
• displayName
• mail
• userPrincipalName
• givenName
• surname
2. Case-Insensitive Matching: Searches are not case-sensitive so displayName:john will return the same results as displayName:John.
3. Partial Matches Allowed: The search works for partial matches (e.g., displayName:John returns both "John Doe" and "Johnny Appleseed").
4. No Wildcards (*) Supported: Unlike -Filter, the -Search parameter does not support wildcards like *.
5. Requires -ConsistencyLevel eventual: When using -Search, always include the -ConsistencyLevel eventual parameter for better query performance and count-based queries.
6. Not All Properties are Filterable: Some user attributes (e.g., jobTitle, department) cannot be searched using -Search. Use -Filter instead for such queries.

By leveraging the -Search parameter effectively, administrators can quickly find users in large Microsoft 365 environments. Mastering these techniques will significantly improve user lookup efficiency in Graph PowerShell.