Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
531 lines (484 sloc) 21.5 KB

Table of Contents

Intune-PowerShell-SDK

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.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Getting started

One-time setup (PowerShell Gallery)

  1. 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)

  1. Download the module from the Releases tab in the GitHub repository.
  2. 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.
  3. 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.
  4. Import the module:
Import-Module $sdkDir/Microsoft.Graph.Intune.psd1

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:

Connect-MSGraph -AdminConsent

Each time you use the module

To authenticate with Microsoft Graph (this is not required when using CloudShell):

Connect-MSGraph

To authenticate with Microsoft Graph using [System.Management.Automation.PSCredential]

$adminUPN=Read-Host -Prompt "Enter UPN"
$adminPwd=Read-Host -AsSecureString -Prompt "Enter password for $adminUPN"
$creds = New-Object System.Management.Automation.PSCredential ($AdminUPN, $adminPwd)
$connection = Connect-MSGraph -PSCredential $creds

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>

Basics

List Objects

Get all Intune applications:

Get-IntuneMobileApp

Filter objects

Use -Select to restrict properties to display:

Get-IntuneMobileApp -Select displayName, publisher

Use -Filter to filter results:

Get-IntuneMobileApp -Select displayName, publisher -Filter "contains(publisher, 'Microsoft')"

Bulk create objects

Bulk create multiple webApp objects (they should appear in the Azure Portal)

$createdApps = 'https://www.bing.com', 'https://developer.microsoft.com/graph', 'https://portal.azure.com' `
| ForEach-Object { `
    New-IntuneMobileApp `
        -webApp `
        -displayName $_ `
        -publisher 'IT Professional' `
        -appUrl $_ `
        -useManagedBrowser $false `
}

Display using GridView

1..15 | ForEach-Object { `
    New-IntuneMobileApp `
        -webApp `
        -displayName "Bing #$_" `
        -publisher 'Microsoft' `
        -appUrl 'https://www.bing.com' `
        -useManagedBrowser ([bool]($_ % 2)) `
} | Out-GridView

Remove all webApps.

# Remove all web apps
$appsToDelete = Get-IntuneMobileApp -Filter "isof('microsoft.graph.webApp')"
$appsToDelete | Remove-IntuneMobileApp

Paging

Show paging of audit events (run this in a different window).

# Audit events are accessible from the beta schema
Update-MSGraphEnvironment -SchemaVersion 'beta'
Connect-MSGraph

# Make the call to get audit events
$auditEvents = Invoke-MSGraphRequest -HttpMethod GET -Url 'deviceManagement/auditEvents'
$auditEvents # more than 1000 results, so they are wrapped in an object with the nextLink
$auditEvents.value | measure

# We can get the next page
$auditEvents2 = $auditEvents | Get-MSGraphNextPage
$auditEvents.value | measure # have to unwrap the results again

# Get all pages of audit events
$auditEvents = Invoke-MSGraphRequest -HttpMethod GET -Url 'deviceManagement/auditEvents' | Get-MSGraphAllPages

# Switch back to v1.0
Update-MSGraphEnvironment -SchemaVersion 'v1.0'

Getting Extended Debug information

If for some reason, a cmdlet fails. Use Get-MSGraphInfo to get extended information. A sample failure is listed below:

# Call that failed
Invoke-IntuneDeviceCompliancePolicyAssign : 500 Internal Server Error
{
  "error": {
    "code": "InternalError",
    "message": "{\r\n  \"_version\": 3,\r\n  \"Message\": \"An internal server error has occurred - Operation ID (for customer support): 00000000-0000-0000-0000-000000000000 - Activity ID: a02e4ad2-efdb-4ae0-8b36-7c990a228f21 -
Url: https://fef.msua06.manage.microsoft.com/StatelessDeviceConfigurationFEService/deviceManagement/deviceCompliancePolicies%28%27bc4c48a9-4120-4531-8870-f57767d43da4%27%29/microsoft.management.services.api.assign?api-version=2018
-06-29\",\r\n  \"CustomApiErrorPhrase\": \"\",\r\n  \"RetryAfter\": null,\r\n  \"ErrorSourceService\": \"\",\r\n  \"HttpHeaders\": \"{}\"\r\n}",
    "innerError": {
      "request-id": "a02e4ad2-efdb-4ae0-8b36-7c990a228f21",
      "date": "2018-11-28T21:44:56"
    }
  }
}
At line:1 char:1
+ Invoke-IntuneDeviceCompliancePolicyAssign   -deviceCompliancePolicyId ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ConnectionError: (@{Request=; Response=}:PSObject) [Invoke-IntuneDe...ncePolicyAssign], HttpRequestException
    + FullyQualifiedErrorId : PowerShellGraphSDK_HttpRequestError,Microsoft.Intune.PowerShellGraphSDK.PowerShellCmdlets.Invoke_IntuneDeviceCompliancePolicyAssign

# Get Debug information
Get-MSGraphDebugInfo

Request
-------
@{HttpMethod=POST; URL=https://graph.microsoft.com/v1.0/deviceManagement/deviceCompliancePolicies/bc4c48a9-4120-4531-8870-f57767d43da4/assign; Headers=; Content={...

# Look into the Request
(Get-MSGraphDebugInfo).Request

HttpMethod URL                                                                                                                    Headers
---------- ---                                                                                                                    -------
POST       https://graph.microsoft.com/v1.0/deviceManagement/deviceCompliancePolicies/bc4c48a9-4120-4531-8870-f57767d43da4/assign @{Authorization=Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFDNXVuYTBFVUZnVElGOEVsYXh0V2pUam...

# Look into the Response
(Get-MSGraphDebugInfo).Response

HttpStatusCode HttpStatusPhrase      Headers
-------------- ----------------      -------
           500 Internal Server Error @{Transfer-Encoding=chunked; request-id=a02e4ad2-efdb-4ae0-8b36-7c990a228f21; client-request-id=a02e4ad2-efdb-4ae0-8b36-7c990a228f21; x-ms-ags-diagnostic={"ServerInfo":{"DataCenter":"West Ce...

# Inspect the Response headers
(Get-MSGraphDebugInfo).Response.Headers

Transfer-Encoding         : chunked
request-id                : a02e4ad2-efdb-4ae0-8b36-7c990a228f21
client-request-id         : a02e4ad2-efdb-4ae0-8b36-7c990a228f21
x-ms-ags-diagnostic       : {"ServerInfo":{"DataCenter":"West Central US","Slice":"SliceC","Ring":"1","ScaleUnit":"001","Host":"AGSFE_IN_4","ADSiteName":"WCU"}}
Duration                  : 496.4757
Strict-Transport-Security : max-age=31536000
Cache-Control             : private
Date                      : Wed, 28 Nov 2018 21:44:55 GMT

Scenario Samples

Upload iOS LOB Application

Load the Apps scenario module

Import-Module '.\Apps\Microsoft.Graph.Intune.Apps.psd1'

Upload the iOS LOB app.

# Upload an iOS Line-Of-Business app
$appToUpload = New-MobileAppObject `
    -iosLobApp `
    -displayName "Intune test iOS Lob App" `
    -description 'This is a test iOS LOB app' `
    -publisher 'Test Publisher' `
    -bundleId '' `
    -applicableDeviceType (New-IosDeviceTypeObject -iPad $true -iPhoneAndIPod $true) `
    -minimumSupportedOperatingSystem (New-IosMinimumOperatingSystemObject -v9_0 $true) `
    -fileName 'test.ipa' `
    -buildNumber 'v1' -versionNumber 'v1' -expirationDateTime ((Get-Date).AddDays(90))

# Upload the app file with the app information
$uploadedAppFile = New-LobApp -filePath '.\Apps\test.ipa' -mobileApp $appToUpload

Create Compliance Policies and Assign it to an AAD Group

# Search the AAD Group
$AADGroupId = (Get-Groups -Filter "displayName eq 'Intune POC Users'").id

Create an iOS Compliance Policy

$iOSCompliancePolicy = New-IntuneDeviceCompliancePolicy `
    -iosCompliancePolicy `
    -displayName "Chicago - iOS Compliance Policy" `
    -passcodeRequired $true `
    -passcodeMinimumLength 6 `
    -passcodeMinutesOfInactivityBeforeLock 15 `
    -securityBlockJailbrokenDevices $true `
    -scheduledActionsForRule `
        (New-DeviceComplianceScheduledActionForRuleObject -ruleName PasswordRequired `
            -scheduledActionConfigurations `
                (New-DeviceComplianceActionItemObject -gracePeriodHours 0 `
                -actionType block `
                -notificationTemplateId "" `
                )`
        )

# Assign the newly created compliance policy to the AAD Group
Invoke-IntuneDeviceCompliancePolicyAssign  -deviceCompliancePolicyId $iOSCompliancePolicy.id `
    -assignments `
        (New-DeviceCompliancePolicyAssignmentObject `
            -target `
                (New-DeviceAndAppManagementAssignmentTargetObject `
                    -groupAssignmentTarget `
                    -groupId "$AADGroupId" `
                ) `
        )

Create Android Compliance Policy

$androidCompliancePolicy = New-IntuneDeviceCompliancePolicy `
    -androidCompliancePolicy `
    -displayName "Chicago - Android Compliance Policy"  `
    -passwordRequired $true `
    -passwordMinimumLength 6 `
    -securityBlockJailbrokenDevices $true `
    -passwordMinutesOfInactivityBeforeLock 15 `
    -scheduledActionsForRule `
    (New-DeviceComplianceScheduledActionForRuleObject `
        -ruleName PasswordRequired `
        -scheduledActionConfigurations `
        (New-DeviceComplianceActionItemObject `
            -gracePeriodHours 0 `
            -actionType block `
            -notificationTemplateId "" `
        )`
    )

# Assign the newly created compliance policy to the AAD Group
Invoke-IntuneDeviceCompliancePolicyAssign -deviceCompliancePolicyId $androidCompliancePolicy.id `
    -assignments `
    (New-DeviceCompliancePolicyAssignmentObject `
        -target `
        (New-DeviceAndAppManagementAssignmentTargetObject `
            -groupAssignmentTarget `
            -groupId "$AADGroupId" `
        ) `
    )

Create Windows 10 Compliance Policy

$windows10CompliancePolicy = New-IntuneDeviceCompliancePolicy `
    -windows10CompliancePolicy `
    -displayName "Chicago - Windows 10 Compliance Policy" `
    -osMinimumVersion 10.0.16299 `
    -scheduledActionsForRule `
    (New-DeviceComplianceScheduledActionForRuleObject `
        -ruleName PasswordRequired `
        -scheduledActionConfigurations `
        (New-DeviceComplianceActionItemObject `
            -gracePeriodHours 0 `
            -actionType block `
            -notificationTemplateId "" `
        ) `
    )

# Assign the newly created compliance policy to the AAD Group
Invoke-IntuneDeviceCompliancePolicyAssign -deviceCompliancePolicyId $windows10CompliancePolicy.id `
    -assignments `
        (New-DeviceCompliancePolicyAssignmentObject `
            -target `
            (New-DeviceAndAppManagementAssignmentTargetObject `
                -groupAssignmentTarget `
                -groupId "$AADGroupId" `
            ) `
        )

Create MacOS Compliance Policy

$macOSCompliancePolicy = New-IntuneDeviceCompliancePolicy `
    -macOSCompliancePolicy `
    -displayName "Chicago - MacOS Compliance Policy" `
    -passwordRequired $true `
    -passwordBlockSimple $false `
    -passwordRequiredType deviceDefault `
    -scheduledActionsForRule `
    (New-DeviceComplianceScheduledActionForRuleObject `
        -ruleName PasswordRequired `
        -scheduledActionConfigurations `
        (New-DeviceComplianceActionItemObject `
            -gracePeriodHours 0 `
            -actionType block `
            -notificationTemplateId "" `
        ) `
    )

# Assign the newly created compliance policy to the AAD Group
Invoke-IntuneDeviceCompliancePolicyAssign -deviceCompliancePolicyId $macOSCompliancePolicy.id `
    -assignments `
    (New-DeviceCompliancePolicyAssignmentObject `
    -target `
        (New-DeviceAndAppManagementAssignmentTargetObject `
            -groupAssignmentTarget `
            -groupId "$AADGroupId" `
        )`
    )

Create Configuration Policies and Assign it to an AAD Group

# Search the AAD Group
$AADGroupId = (Get-Groups -Filter "displayName eq 'Intune POC Users'").id

Create iOS Restriction Policy

$iosGeneralDeviceConfiguration = New-IntuneDeviceConfigurationPolicy `
    -iosGeneralDeviceConfiguration `
    -displayName "Chicago - iOS Device Restriction Policy" `
    -iCloudBlockBackup $true `
    -iCloudBlockDocumentSync $true `
    -iCloudBlockPhotoStreamSync $true

# Assign the newly created configuration policy to the AAD Group
Invoke-IntuneDeviceConfigurationPolicyAssign -deviceConfigurationId $iosGeneralDeviceConfiguration.id `
    -assignments `
    (New-DeviceConfigurationAssignmentObject `
        -target `
        (New-DeviceAndAppManagementAssignmentTargetObject `
            -groupAssignmentTarget `
            -groupId "$AADGroupId" `
        ) `
    )

Create Android Restriction Policy

$androidGeneralDeviceConfiguration = New-IntuneDeviceConfigurationPolicy `
    -androidGeneralDeviceConfiguration `
    -displayName "Chicago - Android Device Restriction Policy" `
    -passwordRequired $true `
    -passwordRequiredType deviceDefault `
    -passwordMinimumLength 4

# Assign the newly created configuration policy to the AAD Group
Invoke-IntuneDeviceConfigurationPolicyAssign -deviceConfigurationId $androidGeneralDeviceConfiguration.id `
    -assignments `
        (New-DeviceConfigurationAssignmentObject `
        -target `
            (New-DeviceAndAppManagementAssignmentTargetObject `
                -groupAssignmentTarget -groupId "$AADGroupId" `
            ) `
        )

Create App Protection Polies and assign it to an AAD Group

iOS App Protection Policy Creation

# Get the list of iOS managed mobileapp objects
$appsiOS = @()
$iosManagedAppProtectionApps = Get-IntuneMobileApp | ? { $_.appAvailability -eq "global" -and ($_.'@odata.type').contains("managedIOS") }
foreach($app in $iosManagedAppProtectionApps)
{
    $bundleId = $app.bundleId
    $appsiOS += (New-ManagedMobileAppObject -mobileAppIdentifier (New-MobileAppIdentifierObject -iosMobileAppIdentifier -bundleId "$bundleId"))
}

# Create the ios App Protection Policy
$iosManagedAppProtection = New-IntuneAppProtectionPolicy `
    -iosManagedAppProtection `
    -displayName "iOS MAM / APP Policy" `
    -periodOfflineBeforeAccessCheck (New-TimeSpan -Hours 12) `
    -periodOnlineBeforeAccessCheck (New-TimeSpan -Minutes 30)`
    -allowedInboundDataTransferSources managedApps `
    -allowedOutboundDataTransferDestinations managedApps `
    -allowedOutboundClipboardSharingLevel managedAppsWithPasteIn `
    -organizationalCredentialsRequired $false `
    -dataBackupBlocked $true `
    -managedBrowserToOpenLinksRequired $false `
    -deviceComplianceRequired $false `
    -saveAsBlocked $true `
    -periodOfflineBeforeWipeIsEnforced (New-TimeSpan -Days 30) `
    -pinRequired $true `
    -maximumPinRetries 5 `
    -simplePinBlocked $false `
    -minimumPinLength 4 `
    -pinCharacterSet numeric `
    -periodBeforePinReset (New-TimeSpan -Days 30) `
    -allowedDataStorageLocations @("oneDriveForBusiness","sharePoint") `
    -contactSyncBlocked $false `
    -printBlocked $true `
    -fingerprintBlocked $false `
    -disableAppPinIfDevicePinIsSet $false `
    -apps $appsiOS

# Assign ios App Protection Policy to the AAD Group
Invoke-IntuneAppProtectionPolicyIosAssign -iosManagedAppProtectionId $iosManagedAppProtection.id `
    -assignments `
    (New-TargetedManagedAppPolicyAssignmentObject `
            -target `
            (New-DeviceAndAppManagementAssignmentTargetObject `
            -groupAssignmentTarget -groupId "$AADGroupId" `
            ) `
    )

Android App Protection Policy Creation

# Get the list of Android managed mobileapp objects
$appsAndroid = @()
$AndroidAPPapps = Get-IntuneMobileApp | ? { $_.appAvailability -eq "global" -and ($_.'@odata.type').contains("managedAndroid") }
foreach($app in $AndroidAPPapps)
{
    $PackageId = $app.packageId
    $appsAndroid += (New-ManagedMobileAppObject -mobileAppIdentifier (New-MobileAppIdentifierObject -androidMobileAppIdentifier -packageId "$PackageId"))
}

# Create the Android App Protection Policy
$androidManagedAppProtectionPolicy = New-IntuneAppProtectionPolicy `
    -androidManagedAppProtection -displayName "Android MAM / APP Policy" `
    -periodOfflineBeforeAccessCheck (New-TimeSpan -Hours 12) `
    -periodOnlineBeforeAccessCheck (New-TimeSpan -Minutes 30)`
    -allowedInboundDataTransferSources managedApps `
    -allowedOutboundDataTransferDestinations managedApps `
    -allowedOutboundClipboardSharingLevel managedAppsWithPasteIn `
    -organizationalCredentialsRequired $false `
    -dataBackupBlocked $true `
    -managedBrowserToOpenLinksRequired $false `
    -deviceComplianceRequired $false `
    -saveAsBlocked $true `
    -periodOfflineBeforeWipeIsEnforced (New-TimeSpan -Days 30) `
    -pinRequired $true `
    -maximumPinRetries 5 `
    -simplePinBlocked $false `
    -minimumPinLength 4 `
    -pinCharacterSet numeric `
    -periodBeforePinReset (New-TimeSpan -Days 30) `
    -allowedDataStorageLocations @("oneDriveForBusiness","sharePoint") `
    -contactSyncBlocked $false `
    -printBlocked $true `
    -disableAppPinIfDevicePinIsSet $false `
    -screenCaptureBlocked $true `
    -apps $appsAndroid

# Assign Android App Protection Policy to the AAD Group
Invoke-IntuneAppProtectionPolicyAndroidAssign -androidManagedAppProtectionId $androidManagedAppProtectionPolicy.id `
    -assignments `
    (New-TargetedManagedAppPolicyAssignmentObject `
            -target `
            (New-DeviceAndAppManagementAssignmentTargetObject `
            -groupAssignmentTarget -groupId "$AADGroupId" `
            ) `
    )

Visualize summary of apps by type

# Get all apps
$apps = Get-IntuneMobileApp

# Group the apps by type
$appsGroupedByType = $apps | Group-Object -Property '@odata.type'

# Get the X axis and Y axis values for the graph (casting is required here)
[string[]]$XVals = $appsGroupedByType | ForEach-Object {$_.Name.Replace('#microsoft.graph.', '')}
[int[]]$YVals = $appsGroupedByType | ForEach-Object {$_.Count}

# Display the results
.\Apps\VisualizeData.ps1 `
    -Title 'Intune Apps by Type' `
    -ChartType 'Pie' `
    -XLabel 'App Type' -YLabel 'Number of Apps' `
    -XValues $XVals -YValues $YVals