Jump to content


anyweb

Getting started with Microsoft Graph and using PowerShell to automate things in Intune

Recommended Posts

Introduction

According to Microsoft, Microsoft Graph is:

    …your entry to automate things in the cloud via the Microsoft Graph API. This API gives you access to AzureAD, Excel, Intune,  Outlook, OneDrive, OneNote, SharePoint, and more.

    Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. After you register your app and get authentication tokens for a user or service, you can make requests to the Microsoft Graph API. This API uses the following HTTP methods:

        Get
        Post
        Patch
        Put
        Delete

    For example, here is a Post action to RemoteLock a device:

    POST https://graph.microsoft.com/Beta/managedDevices/fd3e81ec-a7d0-4f35-af7c-1478213f56c7/remoteLock

If you’d like to play with it right now then you can also check out Graph Explorer, which is a web based (web browser) gui for controlling Graph and it’s available here.

OK that’s already a bit complicated for some people, so what does this mean in real terms for a Microsoft Intune admin that wants to automate things using PowerShell.

In this guide I’ll show you step-by-step how to get up and running with Graph for Intune and how to begin automating actions using PowerShell. This is not for the feint hearted but I encourage you to take the time and effort to try this for yourself, you’ll be glad you did !

Note: In this guide I assume that you already have a Microsoft test Intune tenant setup and configured and that you have some PowerShell knowledge. At the time of writing (August 2017), Graph for Intune is still in Beta and is subject to change. Use of these APIs in production applications is not supported by Microsoft.

Step 1. Download the sample PowerShell scripts

Before you get started, you’ll need to download the PowerShell sample scripts. You can download the Graph PowerShell Intune samples from Github at the following address:

https://github.com/microsoftgraph/powershell-intune-samples


Make sure you have the latest scripts

If you have the latest scripts, then skip this section. The scripts are updated from time to time, so if you downloaded them in the past, go to Github again and download the latest copy of the scripts, chances are that the scripts have been updated and that can mean bugs are fixed or behavior has changed.

For example The following script Invoke_DeviceActionSet.ps1 had this content in June 2017 in the ManagedDevices section

param
(
[switch]$RemoteLock,
[switch]$ResetPasscode,
[switch]$Wipe,
[switch]$Retire,
[Parameter(Mandatory=$true,HelpMessage=”DeviceId (guid) for the Device you want to take action on must be specified:”)]
$DeviceID
)

The same script in August 2017 has been updated to include more ability

param
(
[switch]$RemoteLock,
[switch]$ResetPasscode,
[switch]$Wipe,
[switch]$Retire,
[switch]$Delete,
[switch]$Sync,
[Parameter(Mandatory=$true,HelpMessage=”DeviceId (guid) for the Device you want to take action on must be specified:”)]
$DeviceID
)

In addition there can be behavior changes within the script, for example in the below section (from June 2017) it invokes a RemoteLock action by default

write-host “User” $User.userPrincipalName “has device” $Device.deviceName
Invoke-DeviceAction -DeviceID $Device.id -RemoteLock -Verbose
#Invoke-DeviceAction -DeviceID $Device.id -Retire -Verbose
#Invoke-DeviceAction -DeviceID $Device.id -Wipe -Verbose

The same script in August 2017 does not do any action by default, you’d need to un- comment the appropriate line if you want it to perform a specific action or just edit the script to your liking.

write-host “User” $User.userPrincipalName “has device” $SelectedDevice.deviceName
#Invoke-DeviceAction -DeviceID $SelectedDeviceId -RemoteLock -Verbose
#Invoke-DeviceAction -DeviceID $SelectedDeviceId -Retire -Verbose
#Invoke-DeviceAction -DeviceID $SelectedDeviceId -Wipe -Verbose
#Invoke-DeviceAction -DeviceID $SelectedDeviceId -Delete -Verbose
#Invoke-DeviceAction -DeviceID $SelectedDeviceId -Sync -Verbose


What’s in the script samples ?

The script samples are neatly organized into 15 different sections listed below:

    AppleEnrollment
    Applications
    AppProtectionPolicy
    Authentication
    CheckStatus
    CompanyPortalBranding
    CompliancePolicy
    DeviceConfiguration
    EnrollmentRestrictions
    ManagedDevices
    Paging
    RBAC
    RemoteActionAudit
    TermsAndConditions
    UserPolicyReport

Within each section you’ll find one or more sample PowerShell scripts and there is a readme.md file included in each section which gives more details about what functions are contained in the scripts and what the scripts actually do.

readme.png

Step 2. Install the AzureAD PowerShell module

The first time you attempt to run one of the scripts, a function within the script will check for the AzureAD PowerShell module and if not found it will prompt the user to install the module and it will then exit from the script.

azuread powershell module not installed.png

To avoid this, start PowerShell ISE as administrator, then issue the following command:

Install-Module AzureAD

After entering that command, you’ll get one or more popups asking if it’s OK to download and install NuGet, answer yes to all.

install nuget.png

and then it will start installing the module.

installing package AzureAD.png

You are now ready to test the scripts.


Step 3. AzureAD admin versus target user

When you run one of the sample scripts (for the first time, after installing the AzureAD module) you’ll get prompted for AzureAd credentials to access Intune resources, these are the credentials that you’d normally use to do administrative work in the Intune service in Azure.

In this example you’ll use the Invoke_DeviceAction_set.ps1 script in the ManagedDevices section, open that script using PowerShell ISE as administrator.

Click on the green triangle to Run the script. As you can see it prompts for the user principal name for  Azure  authentication.

specify user principal name for azure authentication.png

For this blogpost, I’m connecting to Azure using a user that has a Directory role of a Global Administrator.

Directory role.png

Tip: You can verify the directory role a user has in Intune, by selecting Users and groups – all users, user, Directory role. Global administrators have full control over all directory resources, if that’s not what you want you can customize the permissions using Limited Administrator and selecting the various options available.

After entering the AzureAD user principal name, you’ll see a popup requesting permission to access various Intune resources, click Accept.

authorize microsoft intune powershell.png

The currently available actions in the Invoke_DeviceAction_Set.ps1 script are

• RemoteLock
• Retire
• Wipe
• Delete
• Sync

To use any of those actions on a device you’ll need to identify a target user (and their associated devices). To do this, enter the user principle name of that target user when prompted. This user is a regular user in Intune and not a Limited or Global Administrator.

user principal name.png

Step 4. Perform a Sync action

Once entered, you’ll see any devices registered to that user, in this example, the specified user has 3 devices assigned.

user has 3 devices.png

Press a number matching the device and… nothing will happen, the script exits.

This is ok as the behavior of the script is modified to perform this way, let’s make a change so that instead of simply exiting, that it will perform a device Sync action.

Locate line 599 in the script which contains this text

sync line.png

and remove the hash in front of that line. Save the file.

599 hash removed and saved.png

Before running the script again, verify the last sync time of the device you want to test automation against. You can verify last sync time by selecting All Devices, find the device in question and look at the Last check-in time column.

last check in time.png

Run the script again and notice the difference, now you are prompted if you want to sync the device.

Go back into Intune and verify the Last Check-in time. It will have changed for that device.

last check in after.png

Success ! You’ve accomplished your first automation using PowerShell in Intune.


Step 5. Perform a device Wipe

Note: A Wipe will reset a device and remove all apps and data on the device, both Personal and Company owned data.

Next, let’s try another action and one that would be very useful to Automate, that is the ability to remove data on a device.

In PowerShell ISE, place a # infront of the Sync line again, and remove the # from the Wipe line. Save the changes.

wipe line.png

Run the script again, notice that you are prompted if you want to to wipe the device this time.

wipe the device.png

and look what happens next !

resetting this pc.png

and in the Intune service in Azure you can see this (Wipe Pending)

wipe pending.png

 

Note: Just because you can see actions in a script does not necessarily mean that those actions will apply to your scenario, and they may infact generate an error, an example of that is the RemoteLock functionality which is not supported on Windows 10 desktop.


Step 5. Perform a device Retire

Note: a Retire action will un-enroll a device from Intune, and remove company data, meaning it is un-managed. All personal apps, data, photos on the device will remain untouched.

In the screenshot below, you can see the Company Portal app installed on an Iphone.

IMG_0007.PNG

And below you can see the Retire action on that same iPhone. In this GIF you can see the line used for the Retire action, and then the fact that the iphone shows up as a device for the user.

Retire an Iphone using Microsoft Graph and PowerShell.gif

After running the action it no longer appears in the device list for that user as it has been removed from device management and is no longer enrolled.

IMG_0010.PNG

Summary

In this blog post you learned a bit about Microsoft Graph, and how you can use it to automate the management of Intune using PowerShell. Awesome, really awesome.

Recommended reading

 

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

Loading...


×
×
  • Create New...

Important Information

We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.