Use Microsoft Graph with REST and PowerShell 7

Personally, i like REST-API´s, especially when they are the direct layer between me and the datasource i want to access. As a PowerShell MVP i often use REST and PowerShell, today i needed to get some data from Microsoft Graph.

The question i needed to answer was: „Which groups is a user member of in the Azure Active Directory.“

I also wanted to use an access method which has only read access to the Azure AD.

(It will take you around 30 minutes to read and get results. This was done using PowerShell 7.0.3 on Windows 10)

So the first step was to create an appliaction (aka ServiceAccount) in the Azure AD:

1.) Create an application in Azure AD

Appliactions are used to authenticate to Azure AD in a script or from an appliction. As an Admin, go you your Azure Portal ==> Azure AD and find „App registrations“.

App registrations menu in Azure AD

Click on „New Registration“ which leads you to this screen:

Give your app a name and enter a valid URL in the „Redirect“ field (the name doesnt really matter).

After the app is created, copy the „Appliaction ID“ and store it somewhere temporarily.

The AppId offers a „copy to clipboard“ option

Now create a client secret (password). In the view for your new app, go to Certificates and secrets. At the bottom find Client secrets and create a new one.

Give your secret a name and a duration (avoid „Never“)

Remember (store somewhere) the secret NOW!

The secret appears and is hidden after storing it, so store it somewhere before closing the dialouge.

The last step to prepare out App is to add it to the Global Reader role. To do this, go to Roles and administrators in the Azure AD main menu.

The Roles and administrators menu in Azure AD

In the search field – enter reader and you will get a result similar to this.

Select the Global reader role, click on assignments ==> Add assignments and select your recently created appliaction. Click on the Add button and verify the change in the assignment page.

Real-world example of an assigned APP in the Global reader role

It might be enough to have the App in the Directory reader role, please test if this makes more sense to you.

2.) Authenticate to Azure and MS-Graph via REST

To read data from the Graph-API, we first need to authenticate and generate a token.

# appId of youe Azure AD Appliaction
$appID = "68000000-0000-0000-0000-00000000000f"
# the secret you generated for the appid
$clientKey = "--------------YOUR-SECRET-HERE--------------"

# The tenant (Azure AD ID) of your tenant ==> Azure AD - properties ... 
$tenantId = "11000000-0000-0000-0000-000000000013"

# Prepare the token request
$url = "https://login.microsoftonline.com/$tenantId/oauth2/token"
# the resource you want the token for
$resource = "https://graph.microsoft.com/" 
# the "body" JSON for the token request, represented in a hashtable.
$restbody = @{
    grant_type = 'client_credentials'
    client_id = $appId
    client_secret = $clientKey
    resource = $resource
}
And now lets call Azure AD for a token !
$token = Invoke-RestMethod -Method POST -Uri $url -Body $restbody

# appId of youe Azure AD Appliaction

$appID = "68000000-0000-0000-0000-00000000000f"

# the secret you generated for the appid

$clientKey = "--------------YOUR-SECRET-HERE--------------"

# The tenant (Azure AD ID) of your tenant ==> Azure AD - properties ...

$tenantId = "11000000-0000-0000-0000-000000000013"

# Prepare the token request

$url = "https://login.microsoftonline.com/$tenantId/oauth2/token"

# the resource you want the token for

$resource = "https://graph.microsoft.com/"

# the "body" JSON for the token request, represented in a hashtable.

$restbody = @{

grant_type = 'client_credentials'

client_id = $appId

client_secret = $clientKey

resource = $resource

}

And now lets call Azure AD for a token !

$token = Invoke-RestMethod -Method POST -Uri $url -Body $restbody

The token object has several properties, but 2 of them are needed for accessing the Graph-API, the token_type and the access_token itself. To verify that your request was working try this:

# This should emit a long string with more that 1000 charachters, the access token.
$token.access_token

1 2	# This should emit a long string with more that 1000 charachters, the access token. $token.access_token

$token.token_type

1	$token.token_type

Great, now lets use the token and create a hasttable with our authentication header!

# Set the baseurl to MS Graph-API
$baseUrl = 'https://graph.microsoft.com/v1.0'

# pack the token into a header hashtable
$header = @{
    'Authorization' = "$($Token.token_type) $($Token.access_token)"
    'Content-type'  = "application/json"
}

# Set the baseurl to MS Graph-API

$baseUrl = 'https://graph.microsoft.com/v1.0'

# pack the token into a header hashtable

$header = @{

'Authorization' = "$($Token.token_type) $($Token.access_token)"

'Content-type' = "application/json"

}

Now the world of the graph API is open to you and its a GREAT ide to read the MS-Graph documentaion https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0

I want to to give you 3 examples, which should be enough to help getting up to speed on how to accomplish more.

3.) Example 1 – List users

First, lets get a list of users in teh AAD

# add the /users string to the URL
$url = $baseUrl + '/users'

# Call the REST-API
Invoke-RestMethod -Method GET -headers $header -Uri $url -outVariable ListUsers

# Our data is now in the variable $listUsers. we are looking for the values
$listUsers.value

# for better formatting and reduced objects we select and format.
$listUsers.value |Select-Object Id,DisplayName,mail,userPrincipalName |Format-Table -AutoSize

# add the /users string to the URL

$url = $baseUrl + '/users'

# Call the REST-API

Invoke-RestMethod -Method GET -headers $header -Uri $url -outVariable ListUsers

# Our data is now in the variable $listUsers. we are looking for the values

$listUsers.value

# for better formatting and reduced objects we select and format.

$listUsers.value |Select-Object Id,DisplayName,mail,userPrincipalName |Format-Table -AutoSize

4.) Example 2 – Get details of a specific user

You saw that the list-user call returned also the objectID. We need this id to query a specific user.

# copy one of the ID´s from the userlist into the UserID variable
$userID = '7e255e7a-a99d-4726-9b84-6f67226ac9f5'

# now modify the url to ask for a specific userid
$url = $baseUrl + '/users' + "/$userid"

# and call the REST-API again
Invoke-RestMethod -Method GET -headers $header -Uri $url -ov OneUser

# our variable $oneUser now contains details about this specific user.
$OneUser

# copy one of the ID´s from the userlist into the UserID variable

$userID = '7e255e7a-a99d-4726-9b84-6f67226ac9f5'

# now modify the url to ask for a specific userid

$url = $baseUrl + '/users' + "/$userid"

# and call the REST-API again

Invoke-RestMethod -Method GET -headers $header -Uri $url -ov OneUser

# our variable $oneUser now contains details about this specific user.

$OneUser

5.) Example 3 – Get group membership of a user

The last example i want to give you is to check the group membership of a particular user.

# first lets extend the url to ask for group membership
$url = $baseUrl + '/users' + "/$userid" + '/memberOf'

# now call the REST-API
Invoke-RestMethod -Method GET -headers $header -Uri $url -ov MemberOf

# read the results and reduce output to 2 members
$MemberOf.value |Select-Object id,DisplayName

# first lets extend the url to ask for group membership

$url = $baseUrl + '/users' + "/$userid" + '/memberOf'

# now call the REST-API

Invoke-RestMethod -Method GET -headers $header -Uri $url -ov MemberOf

# read the results and reduce output to 2 members

$MemberOf.value |Select-Object id,DisplayName

This should hopefully explain the structure of the REST calls and help to bring you up to speed. Read the MS docs in the link above for more and enjoy the Graph REST-API with PowerShell!

Cheers / Roman

2 thoughts on “Use Microsoft Graph with REST and PowerShell 7”

Weekly PowerShell Newsletter | Ridicurious.com
30. Oktober 2020

[…] [Post] […]
PowerShell SnippetRace 44-2020 | | PowerShell Usergroup Austria
1. November 2020

[…] Find out if a user is member or a specific group with teh REST-API and PowerShell. Read this. […]

Comments are closed.