Skip to content

Commit c3b9287

Browse files
Ruchika-mittal01Ruchika-mittal01
authored
Merge pull request #17772 from Erikre/erikre-docs-32145937
Erikre-docs-32145937
2 parents 1bee396 + 41abe73 commit c3b9287

14 files changed

+307
-200
lines changed

‎intune/intune-service/apps/intune-management-extension.md‎

Lines changed: 65 additions & 186 deletions
Large diffs are not rendered by default.

‎intune/intune-service/apps/powershell-scripts.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
---
2+
# required metadata
3+
4+
title: Add PowerShell scripts to Windows 10/11 devices in Microsoft Intune
5+
description: Create and run PowerShell scripts, assign the script policy to Microsoft Entra groups, and use reports to monitor the scripts. See the steps to delete scripts you add on Windows 10/11 devices in Microsoft Intune. Read common issues and resolutions.
6+
keywords:
7+
author: Erikre
8+
ms.author: erikre
9+
manager: dougeby
10+
ms.date: 04/17/2025
11+
ms.topic: how-to
12+
ms.service: microsoft-intune
13+
ms.subservice: apps
14+
ms.localizationpriority: high
15+
ms.assetid:
16+
17+
# optional metadata
18+
19+
#ROBOTS:
20+
#audience:
21+
ms.reviewer: bryanke
22+
ms.suite: ems
23+
search.appverid: MET150
24+
#ms.tgt_pltfrm:
25+
ms.custom: intune-azure
26+
ms.collection:
27+
- tier1
28+
- M365-identity-device-management
29+
- Windows
30+
- highpri
31+
- FocusArea_Apps_Win32
32+
---
33+
34+
# Use PowerShell scripts on Windows 10/11 devices in Intune
35+
36+
Use the Microsoft Intune management extension to upload PowerShell scripts in Intune. Then, run these scripts on Windows 10 devices. The management extension enhances Windows device management (MDM), and makes it easier to move to modern management.
37+
38+
> [!NOTE]
39+
> For information about the Intune management extension for Windows, see [Intune management extension for Windows](../apps/intune-management-extension.md).
40+
41+
## Before you begin
42+
43+
- When scripts are set to user context and the end user has administrator rights, by default, the PowerShell script runs under the administrator privilege.
44+
45+
- End users aren't required to sign in to the device to execute PowerShell scripts.
46+
47+
- The Intune management extension checks after every reboot for any new scripts or changes. After you assign the policy to the Microsoft Entra groups, the PowerShell script runs, and the run results are reported. Once the script executes, it doesn't execute again unless there's a change in the script or policy. If the script fails, the Intune management extension retries the script three times for the next three consecutive Intune management extension check-ins.
48+
49+
- A PowerShell script assigned to the device will run for every new user that signs in, except on multi-session SKUs where user check-in is disabled.
50+
51+
- PowerShell scripts are executed before Win32 apps run. In other words, PowerShell scripts execute first. Then, Win32 apps execute.
52+
53+
- PowerShell scripts time out after 30 minutes.
54+
55+
> [!IMPORTANT]
56+
> Best practices for privacy awareness when using PowerShell scripts and Remediation scripts include the following:
57+
> - Do not include any type of sensitive information in scripts (such as passwords)
58+
> - Do not include Personally Identifiable Information (PII) in scripts
59+
> - Do not use scripts to collect PII from devices
60+
> - Always follow privacy best practices
61+
>
62+
> For related information, see [Remediations](../fundamentals//remediations.md).
63+
64+
## Prerequisites
65+
66+
- Intune management extension installs automatically when a PowerShell script app is assigned to the user or device. For more information, see [Intune management extension for Windows](../apps/intune-management-extension.md).
67+
68+
> [!IMPORTANT]
69+
> Scripts deployed to clients running the Intune management extension will fail to run if the device's system clock is exceedingly out of date by months or years. Once the system clock is brought up to date, script will run as expected.
70+
71+
## Create a script policy and assign it
72+
73+
1. Sign in to the [Microsoft Intune admin center](https://go.microsoft.com/fwlink/?linkid=2109431).
74+
2. Select **Devices** > **Scripts and remediations** > **Platform scripts** > **Add** > **Windows 10 and later**.
75+
76+
![Screenshot that shows creating a new script for a Windows 10 device.](./media/intune-management-extension/create-script-windows.png)
77+
78+
3. In **Basics**, enter the following properties, and select **Next**:
79+
- **Name**: Enter a name for the PowerShell script.
80+
- **Description**: Enter a description for the PowerShell script. This setting is optional, but recommended.
81+
4. In **Script settings**, enter the following properties, and select **Next**:
82+
- **Script location**: Browse to the PowerShell script. The script must be less than 200 KB (ASCII).
83+
- **Run this script using the logged on credentials**: Select **Yes** (default) to run the script with the user's credentials on the device. Choose **No** to run the script in the system context. Many administrators choose **Yes**. If the script is required to run in the system context, choose **No**.
84+
- **Enforce script signature check**: Select **Yes** (default) if the script must be signed by a trusted publisher. Select **No** if there isn't a requirement for the script to be signed.
85+
- **Run script in 64-bit PowerShell host**: Select **Yes** to run the script in a 64-bit PowerShell host on a 64-bit client architecture. Select **No** (default) runs the script in a 32-bit PowerShell host.
86+
87+
When setting to **Yes** or **No**, use the following table for new and existing policy behavior:
88+
89+
| Run script in 64-bit host | Client architecture | New script | Existing policy script |
90+
| --- | --- | --- | --- |
91+
| No | 32-bit | 32-bit PowerShell host supported | Runs only in 32-bit PowerShell host, which works on 32-bit and 64-bit architectures. |
92+
| Yes | 64-bit | Runs script in 64-bit PowerShell host for 64-bit architectures. When ran on 32-bit, the script runs in a 32-bit PowerShell host. | Runs script in 32-bit PowerShell host. If this setting changes to 64-bit, the script opens (it doesn't run) in a 64-bit PowerShell host, and reports the results. When ran on 32-bit, the script runs in 32-bit PowerShell host. |
93+
94+
5. Select **Scope tags**. Scope tags are optional. [Use role-based access control (RBAC) and scope tags for distributed IT](../fundamentals/scope-tags.md) has more information.
95+
96+
To add a scope tag:
97+
98+
- Choose **Select scope tags** > select an existing scope tag from the list > **Select**.
99+
100+
- When finished, select **Next**.
101+
102+
6. Select **Assignments** > **Select groups to include**. An existing list of Microsoft Entra groups is shown.
103+
104+
- Select one or more groups that include the users whose devices receive the script. Choose **Select**. The groups you chose are shown in the list, and will receive your policy.
105+
106+
> [!NOTE]
107+
> PowerShell scripts in Intune can be targeted to Microsoft Entra device security groups or Microsoft Entra user security groups.
108+
> However, when targeting workplace joined (WPJ) devices, only Microsoft Entra device security groups can be used (user targeting will be ignored).
109+
110+
- Select **Next**.
111+
112+
![Assign or deploy PowerShell script to device groups in Microsoft Intune](./media/intune-management-extension/mgmt-extension-assignments.png)
113+
114+
7. In **Review + add**, a summary is shown of the settings you configured. Select **Add** to save the script. When you select **Add**, the policy is deployed to the groups you chose.
115+
116+
### Scenario - Failure to run script
117+
118+
**8 AM**
119+
120+
- Check in
121+
- Run script **ConfigScript01**
122+
- Script fails
123+
124+
**9AM**
125+
126+
- Check in
127+
- Run script **ConfigScript01**
128+
- Script fails (retry count = 1)
129+
130+
**10 AM**
131+
132+
- Check in
133+
- Run script **ConfigScript01**
134+
- Script fails (retry count = 2)
135+
136+
**11 AM**
137+
138+
- Check in
139+
- Run script **ConfigScript01**
140+
- Script fails (retry count = 3)
141+
142+
**12 PM**
143+
144+
- Check in
145+
- No additional attempts are made to run **ConfigScript01**script.
146+
- If no additional changes are made to the script, then no additional attempts are made to run the script.
147+
148+
## Monitor run status
149+
150+
You can monitor the run status of PowerShell scripts for users and devices in the portal.
151+
152+
In **PowerShell scripts**, select the script to monitor, choose **Monitor**, and then choose one of the following reports:
153+
154+
- **Device status**
155+
- **User status**
156+
157+
## Delete a script
158+
159+
In **PowerShell scripts**, right-click the script, and select **Delete**.
160+
161+
## Common issues and resolutions
162+
163+
### Issue: PowerShell scripts do not run
164+
165+
**Possible resolutions**:
166+
167+
- The PowerShell scripts don't run at every sign in. They run:
168+
169+
- When the script is assigned to a device
170+
- If you change the script, upload it, and assign the script to a user or device
171+
172+
> [!TIP]
173+
> The **Microsoft Intune Management Extension** is a service that runs on the device, just like any other service listed in the Services app (services.msc). After a device reboots, this service may also restart, and check for any assigned PowerShell scripts with the Intune service. If the **Microsoft Intune Management Extension** service is set to Manual, then the service may not restart after the device reboots.
174+
175+
- Be sure devices are [joined to Microsoft Entra ID](/azure/active-directory/user-help/user-help-join-device-on-network). Devices that are only joined to your workplace or organization ([registered](/azure/active-directory/user-help/user-help-register-device-on-network) in Microsoft Entra ID) won't receive the scripts.
176+
- Confirm the Intune management extension is downloaded to `%ProgramFiles(x86)%\Microsoft Intune Management Extension`.
177+
- Scripts don't run on Surface Hubs or Windows 10 in S mode.
178+
- Review the logs for any errors. See [Intune management extension logs](../apps/intune-management-extension.md#intune-management-extension-logs) (in this article).
179+
- For possible permission issues, be sure the properties of the PowerShell script are set to `Run this script using the logged on credentials`. Also check that the signed in user has the appropriate permissions to run the script.
180+
181+
- To isolate scripting problems, you can:
182+
183+
- Review the PowerShell execution configuration on your devices. See the [PowerShell execution policy](/powershell/module/microsoft.powershell.security/set-executionpolicy) for guidance.
184+
- Run a sample script using the Intune management extension. For example, create the `C:\Scripts` directory, and give everyone full control. Run the following script:
185+
186+
```powershell
187+
write-output "Script worked" | out-file c:\Scripts\output.txt
188+
```
189+
190+
If it succeeds, output.txt should be created, and should include the "Script worked" text.
191+
192+
- To test script execution without Intune, run the scripts in the System account using the [psexec tool](/sysinternals/downloads/psexec) locally:
193+
194+
`psexec -i -s`
195+
196+
- If the script reports that it succeeded, but it didn't actually succeed, then it's possible your antivirus service may be sandboxing AgentExecutor. The following script always reports a failure in Intune. As a test, you can use this script:
197+
198+
```powershell
199+
Write-Error -Message "Forced Fail" -Category OperationStopped
200+
mkdir "c:\temp"
201+
echo "Forced Fail" | out-file c:\temp\Fail.txt
202+
```
203+
204+
If the script reports a success, look at the `AgentExecutor.log` to confirm the error output. If the script executes, the length should be >2.
205+
206+
- To capture the `.error` and `.output` files, the following snippet executes the script through AgentExecutor to PowerShell x86 (`C:\Windows\SysWOW64\WindowsPowerShell\v1.0`). It keeps the logs for your review. Remember, the Intune Management Extension cleans up the logs after the script executes:
207+
208+
```powershell
209+
$scriptPath = read-host "Enter the path to the script file to execute"
210+
$logFolder = read-host "Enter the path to a folder to output the logs to"
211+
$outputPath = $logFolder+"\output.output"
212+
$errorPath = $logFolder+"\error.error"
213+
$timeoutPath = $logFolder+"\timeout.timeout"
214+
$timeoutVal = 60000
215+
$PSFolder = "C:\Windows\SysWOW64\WindowsPowerShell\v1.0"
216+
$AgentExec = "C:\Program Files (x86)\Microsoft Intune Management Extension\agentexecutor.exe"
217+
&$AgentExec -powershell $scriptPath $outputPath $errorPath $timeoutPath $timeoutVal $PSFolder 0 0
218+
```
219+
220+
### Issue: Why are scripts running even though Windows is no longer managed?
221+
222+
When a Windows device with assigned scripts is no longer managed, the IME isn't removed immediately. The IME detects that the Windows isn't managed at the next IME check-in (usually every 8 hours) and cancels script-runs. In the meantime, any locally stored scripts may run. When the IME is unable to check in, it retries checking in for up to 24 hours (device-awake time) and then removes itself from the Windows device.
223+
224+
## Next steps
225+
226+
[Monitor](../configuration/device-profile-monitor.md) and [troubleshoot](../configuration/device-profile-troubleshoot.md) your profiles.

‎intune/intune-service/configuration/device-profile-create.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ Profiles are created in the [Microsoft Intune admin center](https://go.microsoft
7474
- **Overview**: Lists the status of your profiles, and provides more details on the profiles you assigned to users and devices.
7575
- **Monitor**: Check the status of your profiles for success or failure, and also view logs on your profiles.
7676
- **By platform**: Create and view policies and profiles by your platform. This view can also show features specific to the platform. For example, select **Windows 10 and later**. You see Windows-specific features, such as **Windows Update Rings** and **PowerShell scripts**.
77-
- **Manage devices**: Create device profiles, upload custom [PowerShell scripts](../apps/intune-management-extension.md) to run on devices, and add data plans to devices using [eSIM](esim-device-configuration.md).
77+
- **Manage devices**: Create device profiles, upload custom [PowerShell scripts](../apps/powershell-scripts.md) to run on devices, and add data plans to devices using [eSIM](esim-device-configuration.md).
7878

7979
When you create a profile (**Devices** > **Manage devices** > **Configuration** > **Create**), choose your platform:
8080

‎intune/intune-service/configuration/device-profiles.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -335,7 +335,7 @@ On Linux devices, you can [add existing Bash scripts](../configuration/device-pr
335335

336336
On macOS devices, you can [add existing shell scripts](../apps/macos-shell-scripts.md), and then deploy these scripts to your macOS devices.
337337

338-
On Windows devices, you can use the Intune Management Extension to upload your [PowerShell scripts](../apps/intune-management-extension.md) in Intune, and then run these scripts on your devices. Also see what's required to use the extension, how to add them to Intune, and other important information.
338+
On Windows devices, you can use the Intune Management Extension to upload your [PowerShell scripts](../apps/powershell-scripts.md) in Intune, and then run these scripts on your devices. Also see what's required to use the extension, how to add them to Intune, and other important information.
339339

340340
This feature supports:
341341

‎intune/intune-service/developer/reports-ref-devices.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -270,7 +270,7 @@ The **devices** entity lists all enrolled devices under management and their cor
270270
| windowsOsEdition | Windows Operating System edition. |
271271
| ethernetMacAddress | The unique network identifier of this device. |
272272
| model | The device model. |
273-
| office365Version | The version of Microsoft 365 that is installed on the device. `Office365Version` is only collected when the Intune management extension agent is installed on a Windows machine. The admin must also create and assign a PowerShell or Win32 App for the agent to be installed. For more information, see [Use PowerShell scripts on Windows 10 devices in Intune](../apps/intune-management-extension.md) and [Win32 app management in Microsoft Intune](../apps/apps-win32-app-management.md).<p>**NOTE**:<br>There's a known issue with the Intune Data Warehouse **devices** table. The `office365Version` property for the device record may be null. This property is currently under maintenance and may be subject to deprecation. Therefore, you should consider not using this property value for reporting purposes. |
273+
| office365Version | The version of Microsoft 365 that is installed on the device. `Office365Version` is only collected when the Intune management extension agent is installed on a Windows machine. The admin must also create and assign a PowerShell or Win32 App for the agent to be installed. For more information, see [Use PowerShell scripts on Windows 10 devices in Intune](../apps/powershell-scripts.md) and [Win32 app management in Microsoft Intune](../apps/apps-win32-app-management.md).<p>**NOTE**:<br>There's a known issue with the Intune Data Warehouse **devices** table. The `office365Version` property for the device record may be null. This property is currently under maintenance and may be subject to deprecation. Therefore, you should consider not using this property value for reporting purposes. |
274274
| SubnetAddressV4Wifi | The subnet address for IPV4 Wifi connection. |
275275
| IpAddressV4Wifi | The IP address for IPV4 Wifi connection. |
276276

‎intune/intune-service/fundamentals/cloud-configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ Using Microsoft Intune, you can use a guided scenario to deploy a cloud configur
9090

9191
- Deploys a Windows PowerShell script that removes built-in apps, and simplifies the Start menu.
9292

93-
For information about PowerShell scripts in Intune, go to [Use PowerShell scripts on Windows client devices](../apps/intune-management-extension.md).
93+
For information about PowerShell scripts in Intune, go to [Use PowerShell scripts on Windows client devices](../apps/powershell-scripts.md).
9494

9595
- Creates a Windows client update ring policy. This policy automatically updates the devices, including product updates, drivers, and Windows updates.
9696

‎intune/intune-service/fundamentals/deployment-guide-platform-windows.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ As you set up apps and app policies, think about your organization's requirement
134134
|[Add Microsoft 365 apps](../apps/apps-add-office365.md) |Add Microsoft 365 Apps for enterprise. |
135135
|[Assign apps to groups ](../apps/apps-deploy.md)|After you add apps to Intune, assign them to users and devices.|
136136
|[Include and exclude app assignments ](../apps/apps-inc-exl-assignments.md)|Control access and availability to an app by including and excluding selected groups from assignment.|
137-
|[Use PowerShell scripts](../apps/intune-management-extension.md)|Upload PowerShell scripts to extend Windows device management capabilities in Intune and make it easier to move to modern management.|
137+
|[Use PowerShell scripts](../apps/powershell-scripts.md)|Upload PowerShell scripts to extend Windows device management capabilities in Intune and make it easier to move to modern management.|
138138

139139
## Step 8: Enroll devices
140140

‎intune/intune-service/fundamentals/deployment-plan-configuration-profile.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -557,7 +557,7 @@ This level expands on what you configured in levels 1 and 2. It adds extra secur
557557
- **Deploy shell scripts**:
558558

559559
- [**macOS**: Use shell scripts](../apps/macos-shell-scripts.md)
560-
- [**Windows**: Use Windows PowerShell scripts](../apps/intune-management-extension.md)
560+
- [**Windows**: Use Windows PowerShell scripts](../apps/powershell-scripts.md)
561561

562562
## Follow the minimum recommended baseline policies
563563

0 commit comments

Comments
 (0)