Friday, 15 November 2019

Export Office 365 Users using Graph API in Powershell

In Powershell, you can easily get Azure AD user details using the Azure AD Powershell command Get-AzureADUser. In some cases, we may be required to use Microsoft Graph API to query details from Azure AD or other Office 365 services. In this post, I am going to explain how to retrieve user details from Azure AD using Graph API and export details to CSV file in Powershell.

Based on your need, you have to acquire Graph Access token using Azure AD Application with below permission scopes.
  • User.ReadBasic.All - Read all users' basic profiles.
  • User.Read.All - Read all users' full profiles.
In this post, I am going to use PnP.PowerShell app to get access token. Install the PnP Online Powershell module and run the below commands to get graph access token with required permission scopes.
Connect-PnPOnline -Scopes "User.Read.All"
$AccessToken =Get-PnPAccessToken
You can refer Microsoft Graph Documentation to know more about required permissions for every end-point URL.

Call Microsoft Graph API and get users data:

Once you have acquired the required access token, you can easily query graph api using the Invoke-RestMethod cmdlet by passing the $AccessToken.
$ApiUrl = ""
$Response = Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Get
$Users = $Response.value
By default, the API call returns only 100 users and we have to set the $top parameter to get more users. Also in a single API call, we can get only 1000 users. If you have more than 1000 users, we have to make another request with nextLink token to get another 1000 users and we need to loop this process until we get the nextLink token as a null value.
$Result = @()
$ApiUrl = "`$top=999"
$Response = Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Get
$Users = $Response.value
$Result = $Users

While ($Response.'@odata.nextLink' -ne $null) {
$Response = Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $Response.'@odata.nextLink' -Method Get
$Users = $Response.value
$Result += $Users
Note: In Powershell $ is the special character, so we need to put escape character ` (back-tick) before $ symbol in string (ex: `$).

Export Users to CSV file

You can export the result to CSV file using the Export-CSV cmdlet.
$Result | Export-CSV "C:\\O365Users.CSV" -NoTypeInformation -Encoding UTF8
Export only selected fields:
$Result | Select displayName,userPrincipalName, mail |
Export-CSV "C:\\O365Users.CSV" -NoTypeInformation -Encoding UTF8

Request users with selected properties

You can use the $select query parameter to retrieve only the required set of user properties. For example, to return displayName, jobTitle, and mail, you need to add the query $select=displayName,jobTitle,mail in your users endpoint api url.
$ApiUrl = "`$select=displayName,jobTitle,mail"
Note: If you do not specify $select query, by default, only a limited set of properties are returned ( businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName ). To return additional properties (ex: accountEnabled, assignedLicenses, assignedPlans, etc..), you must specify the desired set of user properties using the $select query.
$ApiUrl = "`$select=displayName,assignedPlans,accountEnabled"
You can refer OData select parameter to know more about select query.

Request users with filter query parameter

You can limit the results by filtering users in the server-side by specifying the $filter query parameter. For example, if you want to limit users by their department, you can use the below query.
$ApiUrl = "`$filter=Department eq 'Sales'"
You can refer OData filter parameter to know more about filter query.

Request users with select, filter and top parameters in a single query

You have to join multiple query parameters with AND ("&") symbol.
$ApiUrl = "`$filter=Department eq 'Sales'&`$select=displayName,mail&`$top=999"


No comments:

Post a Comment