Table of Contents
- Table of Contents
- Getting started
- Example usage
- Notable features
- Known issues and workarounds
This repository contains the source code for the PowerShell module which provides support for the Intune API through Microsoft Graph.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
One-time setup (PowerShell Gallery)
- Install the Microsoft.Graph.Intune module from: https://www.powershellgallery.com/packages/Microsoft.Graph.Intune
Install-Module -Name Microsoft.Graph.Intune
One-time setup (GitHub)
- Download the module from the Releases tab in the GitHub repository.
- The "drop\outputs\build\Release\net471" folder in the zip file contains the module.
- If you are using Windows, extract the "net471" folder. You must have .NET 4.7.1 or higher installed.
- The module manifest is the "Microsoft.Graph.Intune.psd1" file inside this folder. This is the file you would refer to when importing the module.
- Import the module:
Before this module is used in your organization
An admin user must provide consent for this app to be used in their organization. This can be done with the following command:
Each time you use the module
To authenticate with Microsoft Graph (this is not required when using CloudShell):
To authenticate with Microsoft Graph using a [PSCredential] object:
# 1. Create the PSCredential object $adminUPN = Read-Host -Prompt "Enter UPN" $adminPwd = Read-Host -AsSecureString -Prompt "Enter password for $adminUPN" $creds = New-Object System.Management.Automation.PSCredential ($adminUPN, $adminPwd) # 2. Log in with these credentials Connect-MSGraph -PSCredential $creds
To authenticate in a non-standard environment:
# 1. Setup the environment # For example, in a National Cloud environment, the following is required before logging in Update-MSGraphEnvironment -AuthUrl 'https://login.microsoftonline.us/common' -GraphBaseUrl 'https://graph.microsoft.us' -GraphResourceId 'https://graph.microsoft.us' -SchemaVersion 'beta' # 2. Log in Connect-MSGraph # 3. Use the cmdlets # NOTE: If the schema version has been changed to something other than "v1.0" as in the above # "Update-MSGraphEnvironment" command, only "Invoke-MSGraphRequest" should be used to make calls, # because the standard cmdlets (e.g. "Get-IntuneMobileApp") have been generated based on the # "v1.0" schema, and can produce unexpected results when used with other schema versions Invoke-MSGraphRequest -HttpMethod GET -Url 'deviceAppManagement/mobileApps'
Discovering available commands
Get the full list of available cmdlets:
Get-Command -Module Microsoft.Graph.Intune
Get documentation on a particular cmdlet:
Get-Help <cmdlet name>
Use a UI to see the parameter sets more easily:
Show-Command <cmdlet name>
Get all Intune applications:
Get all Intune device configurations:
Get all Intune managed devices:
Get a filtered list of applications and select only the "displayName" and "publisher" properties:
# The filter string follows the same rules as specified in the OData v4.0 specification. # Filter string construction rules: http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/abnf/odata-abnf-construction-rules.txt Get-IntuneMobileApp -Select displayName, publisher -Filter "isof('microsoft.graph.webApp')"
Create a web application:
$bingWebApp = New-IntuneMobileApp -webApp -displayName 'Bing' -publisher 'Microsoft Corporation' -AppUrl 'https://www.bing.com'
Update the web application that we created in the 'Creating objects' section:
$bingWebApp | Update-IntuneMobileApp -webApp -displayName 'Bing Search'
Delete the web application that we created in the 'Creating objects' section:
$bingWebApp | Remove-IntuneMobileApp
Calling functions and actions
Lock a managed device:
# Get a device to lock $allDevices = Get-IntuneManagedDevice $deviceToLock = $allDevices # Lock this device $deviceToLock | Invoke-IntuneManagedDeviceRemoteLock
Tips and Tricks
- Create TimeSpan objects using the New-TimeSpan cmdlet
- Create DateTime or DateTimeOffset objects using the Get-Date cmdlet
- If a parameter accepts an "Object" rather than a more specific type, use the documentation to identify what type of object it requires. For example, if the documentation says that a parameter represents a property of type "microsoft.graph.mobileApp" or "microsoft.graph.deviceConfiguration", use the "New-MobileAppObject" or "New-DeviceConfigurationObject" cmdlets to create the respective objects.
- Standard PowerShell objects are used for input/output, meaning that all built-in PowerShell features/utilities/tricks work, including:
- Piping of objects between cmdlets
- Formatting of output:
- Getting help on usage:
- Visualizing input parameters:
- Using the 'tab' key to auto-complete or cycle through available options
- Documentation which is available in the schema is injected into the cmdlet documentation
- Auto-complete and validation on Enum parameters as well as some query parmeters (i.e. $select, $expand and $orderBy)
- Utility cmdlets for some common tasks
- Getting the authentication token:
- Getting service metadata:
- Changing environment settings, e.g. Graph schema version:
Update-MSGraphEnvironment -Schema beta -AppId 00000000-0000-0000-0000-000000000000
- Make arbitrary Graph calls using the
- Getting the authentication token:
- The PowerShell module can be generated for any valid Graph schema
Known issues and workarounds
- Importing the
MSOnlinecmdlets before importing this
Intunemodule will cause errors. Please use the
AzureADmodule instead, as the
MSOnlinemodule is deprecated.
- If you absolutely must use the
MSOnlinemodule, it should be imported AFTER the
Intunemodule. Note, however, that this is not officially supported.
- If you absolutely must use the
- If downloaded from Github, the file "Microsoft.Intune.PowerShellGraphSDK.dll" may be blocked when a release is first downloaded. This will stop the assembly from correctly loading (and you will see an error message if you try to import the module).
Dir -Recurse $sdkDir | Unblock-File
- Cmdlets in this module are generated based on the "v1.0" version of the Graph schema. In order to access functionality in the "beta" schema you must change the schema version using the command below. However, note that only the
Invoke-MSGraphRequestcmdlet should be used to make calls to Graph. This is because the difference in entities/properties between "beta" and "v1.0" (the schema that most cmdlets were generated from) can result in unexpected behavior.
Update-MSGraphEnvironment -SchemaVersion 'beta'