Listing Microsoft 365 Tenant Contacts with Graph PowerShell

Managing contacts in Microsoft 365 (Azure Active Directory) is an essential task for administrators. While the Microsoft 365 admin center provides an interface to view and manage contacts, using PowerShell provides flexibility and automation, particularly when dealing with large organizations. In this article, we will explore how to retrieve a list of all contacts in your Microsoft 365 tenant using Microsoft Graph PowerShell, displaying important details like the contact’s display name and email in a clean tabular format.

The Script

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

# Query the contacts in Azure AD
$contacts = Get-MgContact -All

# Select relevant properties and output in tabular format
$contacts | Select-Object DisplayName Mail | Format-Table -AutoSize

How the Script Works

• Connect to Microsoft Graph: The script first establishes a connection to Microsoft Graph using the Connect-MgGraph cmdlet. The -Scopes parameter specifies the permissions required for this task: User.Read.All and Contacts.Read. These scopes allow the script to read user and contact information from Azure AD.
• Query the contacts: The Get-MgContact cmdlet is then used to query all the contacts in the directory. The -All parameter ensures that all contacts are retrieved even if there are more than the default 100 returned in a single query.
• Select and format the output: The script uses Select-Object to pick the DisplayName and Mail fields, which are the essential properties of a contact. Finally, the Format-Table -AutoSize cmdlet is used to display the results in a clean tabular format, making it easy to read the contact list.

Further Enhancements

• Exporting to a CSV File: You can export the contact list to a CSV file for easier sharing or reporting using the following command:

$contacts | Select-Object DisplayName Mail | Export-Csv -Path "TenantContacts.csv" -NoTypeInformation

This will generate a CSV file containing the list of contacts with their display names and email addresses.

• Filtering Contacts: If you want to filter the contacts based on certain criteria, such as only retrieving contacts with an email address, you can modify the script like so:
`

$contacts = Get-MgContact -All | Where-Object { $_.Mail -ne $null }

• Displaying Additional Fields: You may wish to retrieve other fields like CompanyName, JobTitle, or PhoneNumbers to get more information about the contacts. You can modify the Select-Object to include these fields:

$contacts | Select-Object DisplayName Mail CompanyName JobTitle | Format-Table -AutoSize

Possible Errors & Solutions

Error: Connect-MgGraph: Insufficient privileges to complete the operation.

Cause: You may not have the required permissions to run the script.

Solution: Ensure that your account has been granted the necessary permissions (User.Read.All and Contacts.Read). If you're using application-based authentication, ensure that your app registration has these permissions assigned in Azure AD.

Error: Get-MgContact: A positional parameter cannot be found that accepts argument '-All'.

Cause: This error may occur if the Microsoft Graph PowerShell module is not up to date.

Solution: Update your Microsoft Graph module to the latest version using the following command:

Update-Module Microsoft.Graph

Error: Format-Table: The object doesn't have a property 'Mail'.

Cause: Some contacts may not have a Mail property.

Solution: You can add a check to filter out contacts without an email address using:

$contacts | Where-Object { $_.Mail -ne $null } | Select-Object DisplayName Mail | Format-Table -AutoSize

Error: Authentication failed.

Cause: This can happen if there’s an issue with the authentication process when connecting to Microsoft Graph.

Solution: Ensure that you are using the correct credentials and try reconnecting using:

Disconnect-MgGraph
Connect-MgGraph -Scopes "User.Read.All" "Contacts.Read"

Conclusion

Using Microsoft Graph PowerShell to manage and query Azure AD contacts offers a powerful way to automate daily administrative tasks. The script discussed in this article provides a simple yet effective method for retrieving and displaying tenant contacts, while additional enhancements make it adaptable to various scenarios. As with any script, be sure to test it in your environment and address any errors as they arise. Microsoft Graph continues to grow, making it a valuable tool for any administrator seeking efficient management of Microsoft 365.