deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-20 04:43:37 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

merge

Browse Source
This commit is contained in:
Paolo Matarazzo
2025-02-26 15:57:01 -05:00
parent 688dd9d8a6
commit 5f42050e7e
21 changed files with 836 additions and 838 deletions
Download Patch File Download Diff File Expand all files Collapse all files

343
windows/configuration/assigned-access/index.md
View File

@ -1,74 +1,315 @@
---
title: Windows kiosks and restricted user experiences
description: Learn about the options available in Windows to configure kiosks and restricted user experiences.
ms.topic: overview
title: What is Assigned Access?
description: Learn how to configure a Windows kiosk for single-app and multi-app scenarios with Assigned Access.
ms.date: 10/31/2024
ms.topic: overview
---
# Windows kiosks and restricted user experiences
# What is Assigned Access?
Organizations are constantly seeking ways to streamline operations, improve customer service, and enhance productivity. One effective solution is the deployment of kiosk devices. These specialized devices offer a range of benefits that can significantly impact an organization's efficiency and success. For example:
Assigned Access is a Windows feature that you can use to configure a device as a kiosk or with a restricted user experience.
- Cost-effective customer service: kiosks allow organizations to provide essential services without the need for dedicated staff. Whether it's checking in at a hotel, ordering food at a restaurant, or printing boarding passes at an airport, kiosks reduce labor costs while maintaining service quality. Customers appreciate the convenience of self-service options, leading to higher satisfaction levels
- Reduced wait times: long queues and wait times frustrate customers and staff members. Kiosks expedite processes by allowing users to complete tasks independently. Whether it's paying bills, renewing memberships, or accessing information, kiosks empower users to get things done swiftly
- Consistent brand experience: kiosks ensure a uniform brand experience across different locations. Whether in retail stores, schools, airports, or healthcare facilities, the interface remains consistent. Brand consistency builds trust and reinforces the organization's image
- Customization and flexibility: kiosks can be tailored to specific needs. From touchscreens to barcode scanners, organizations choose features that align with their goals. Whether it's self-checkout, wayfinding, or interactive product catalogs, kiosks adapt to diverse requirements
When you configure a **kiosk experience**, a single Universal Windows Platform (UWP) application or Microsoft Edge is executed in full screen, above the lock screen. Users can only use that application. If the kiosk app is closed, it automatically restarts. Practical examples include:
Windows offers two different options for public or specialized use:
- Public browsing
- Interactive digital signage
:::row:::
:::column span="1":::
:::image type="content" source="images/kiosk.png" alt-text="Icon representing a kiosk." border="false":::
:::column-end:::
:::column span="3":::
#### Kiosk experience
:::column-end:::
:::row-end:::
When you configure a **restricted user experience**, users can only execute a defined list of applications, with a tailored Start menu and Taskbar. Different policy settings and AppLocker rules are enforced, creating a locked down experience. The users can access a familiar Windows desktop, while limiting their access, reducing distractions, and potential for inadvertent uses. Ideal for shared devices, you can create different configurations for different users. Practical examples include:
This option runs a single application in full screen, and people using the device can only use that app. When the designated kiosk account signs in, the kiosk app launches automatically. This option is sometimes referred to as *single-app kiosk*.
- Frontline worker devices
- Student devices
- Lab devices
Windows offers two different features to configure a kiosk experience:
> [!NOTE]
> When you configure a restricted user experience, different policy settings are applied to the device. Some policy settings apply to standard users only, and some to administrator accounts too. For more information, see [Assigned Access policy settings](policy-settings.md).
- **Assigned Access**: used to execute a single Universal Windows Platform (UWP) app or Microsoft Edge in full screen above the lock screen. When the kiosk account signs in, the kiosk app launches automatically. If the UWP app is closed, it automatically restarts
- **Shell Launcher**: used to configure a device to execute a Windows desktop application as the user interface. The application that you specify replaces the default Windows shell (`Explorer.exe`) that usually runs when a user signs in. This type of single-app kiosk doesn't run above the lock screen
## Requirements
:::row:::
:::column span="1":::
:::image type="content" source="images/restricted-user-experience.png" alt-text="Icon representing a restricted user experience." border="false":::
:::column-end:::
:::column span="3":::
#### Restricted user experience
:::column-end:::
:::row-end:::
Here are the requirements for Assigned Access:
This option loads the Windows desktop, but it only allows to run a defined set of applications. When the designated user signs in, the user can only run the apps that are allowed. The Start menu is customized to show only the apps that are allowed to execute. With this approach, you can configure a locked-down experience for different account types. This option is sometimes referred to as *multi-app kiosk*.
- To use a kiosk experience, [User account control (UAC)](/windows/security/identity-protection/user-account-control/user-account-control-overview) must be enabled
- To use a kiosk experience, you must sign in from the console. The kiosk experience isn't supported over a remote desktop connection
:::image type="content" source="images/restricted-user-experience-example.png" alt-text="Screenshot of a restricted user experience in Windows 11." border="false":::
[!INCLUDE [assigned-access](../../../includes/licensing/assigned-access.md)]
To configure a restricted user experience, you use the **Assigned Access** feature.
## Configure a kiosk experience
## Choose the right experience
There are several options to configure a kiosk experience. If you need to configure a single device with a local account, you can use:
When you're considering a kiosk or restricted user experience, you need to choose the right experience for your needs. A good approach is to ask yourself the following set of questions:
- PowerShell: you can use the `Set-AssignedAccess` PowerShell cmdlet to configure a kiosk experience using a local standard account
- Settings: use this option when you need a simple method to configure a single device with a local standard user account
| | Question |
|--|--|
| **🔲** | *How many apps?* <br>The number of apps determines the experience to build: **kiosk** or **restricted user experience**.|
| **🔲** | *Desktop experience or custom?* <br>If your users require access to the desktop with a custom Start menu, then you can build a **restricted user experience** with **Assigned Access**. If your users require access to multiple applications but with a custom user interface, then you should use **Shell Launcher**.|
| **🔲** | *In single-app scenario, which type of app will your kiosk run?* <br>If the kiosk requires a Universal Windows Platform (UWP) app or Microsoft Edge, you can build a **kiosk experience** with **Assigned Access**. If the kiosk requires a desktop app, you can build a **kiosk experience** with **Shell Launcher**.|
| **🔲** | *Which edition of Windows client will the kiosk run?"* <br>**Assigned Access** is supported on Windows Pro and Enterprise/Education. **Shell Launcher** is only supported on Windows Enterprise and Education editions.|
For advanced customizations, you can use the [Assigned Access CSP](/windows/client-management/mdm/assignedaccess-csp) to configure the kiosk experience. The CSP allows you to configure the kiosk app, the user account, and the kiosk app's behavior. When you use the CSP, you must create an XML configuration file that specifies the kiosk app and the user account. The XML file is applied to the device using one of the following options:
- A Mobile Device Management (MDM) solution, like Microsoft Intune
- Provisioning packages
- PowerShell, with the MDM Bridge WMI Provider
To learn how to configure the Shell Launcher XML file, see [Create an Assigned Access configuration file](configuration-file.md).
[!INCLUDE [tab-intro](../../../includes/configure/tab-intro.md)]
#### [:::image type="icon" source="../images/icons/intune.svg"::: **Intune/CSP**](#tab/intune)
You can configure devices using a [custom policy][MEM-1] with the [AssignedAccess CSP][WIN-3].
- **Setting:** `./Vendor/MSFT/AssignedAccess/Configuration`
- **Value:** content of the XML configuration file
Assign the policy to a group that contains as members the devices that you want to configure.
#### [:::image type="icon" source="../images/icons/provisioning-package.svg"::: **PPKG**](#tab/ppkg)
[!INCLUDE [provisioning-package-1](../../../includes/configure/provisioning-package-1.md)]
- **Path:** `AssignedAccess/AssignedAccessSettings`
- **Value:** Enter the account and the application you want to use for Assigned access, using the AUMID of the app. Example:
- `{"Account":"domain\user", "AUMID":"Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"}`
[!INCLUDE [provisioning-package-2](../../../includes/configure/provisioning-package-2.md)]
#### [:::image type="icon" source="../images/icons/powershell.svg"::: **PowerShell**](#tab/ps)
To configure a device using Windows PowerShell:
1. Sign in as administrator
1. [Create the user account](https://support.microsoft.com/help/4026923/windows-create-a-local-user-or-administrator-account-in-windows-10) for Assigned Access
1. Sign in as the Assigned Access user account
1. Install the required UWP app
1. Sign out as the Assigned Access user account
1. Sign in as administrator and from an elevated PowerShell prompt use one of the following commands:
```PowerShell
#Configure Assigned Access by AppUserModelID and user name
Set-AssignedAccess -AppUserModelId <AUMID> -UserName <username>
#Configure Assigned Access by AppUserModelID and user SID
Set-AssignedAccess -AppUserModelId <AUMID> -UserSID <usersid>
#Configure Assigned Access by app name and user name
Set-AssignedAccess -AppName <CustomApp> -UserName <username>
#Configure Assigned Access by app name and user SID**:
Set-AssignedAccess -AppName <CustomApp> -UserSID <usersid>
> [!NOTE]
> To set up Assigned Access using `-AppName`, the user account that you enter for Assigned Access must have signed in at least once.
For more information:
- [Find the Application User Model ID of an installed app](../store/find-aumid.md)
- [Set-AssignedAccess](/powershell/module/assignedaccess/set-assignedaccess)
To remove assigned access, using PowerShell, run the following cmdlet:
```powershell
Clear-AssignedAccess
```
For advanced customizations that use the XML configuration file, you can use PowerShell scripts via the [MDM Bridge WMI Provider](/windows/win32/dmwmibridgeprov/mdm-bridge-wmi-provider-portal).
> [!IMPORTANT]
> For all device settings, the WMI Bridge client must be executed as SYSTEM (LocalSystem) account.
To test the PowerShell script, you can:
1. [Download the psexec tool](/sysinternals/downloads/psexec)
1. Open an elevated command prompt and run: `psexec.exe -i -s powershell.exe`
1. Run the script in the PowerShell session
```PowerShell
$shellLauncherConfiguration = @"
# content of the XML configuration file
"@
$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.ShellLauncher = [System.Net.WebUtility]::HtmlEncode($shellLauncherConfiguration)
$obj = Set-CimInstance -CimInstance $obj -ErrorVariable cimSetError -ErrorAction SilentlyContinue
if($cimSetError) {
Write-Output "An ERROR occurred. Displaying error record and attempting to retrieve error logs...`n"
Write-Error -ErrorRecord $cimSetError[0]
$timeout = New-TimeSpan -Seconds 30
$stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
do{
$events = Get-WinEvent -FilterHashtable $eventLogFilterHashTable -ErrorAction Ignore
} until ($events.Count -or $stopwatch.Elapsed -gt $timeout) # wait for the log to be available
if($events.Count) {
$events | ForEach-Object {
Write-Output "$($_.TimeCreated) [$($_.LevelDisplayName.ToUpper())] $($_.Message -replace "`n|`r")"
}
} else {
Write-Warning "Timed-out attempting to retrieve event logs..."
}
Exit 1
}
Write-Output "Successfully applied Shell Launcher configuration"
```
[!INCLUDE [powershell-wmi-bridge-2](../../../includes/configure/powershell-wmi-bridge-2.md)]
#### [:::image type="icon" source="../images/icons/settings-app.svg"::: **Settings**](#tab/settings)
Here are the steps to configure a kiosk using the Settings app:
1. Open the Settings app to view and configure a device as a kiosk. Go to **Settings > Accounts > Other Users**, or use the following shortcut:
> [!div class="nextstepaction"]
>
> [Other Users](ms-settings:otherusers)
1. Under **Set up a kiosk**, select **Get Started**
1. In the **Create an account** dialog, enter the account name, and select **Next**
>[!NOTE]
>If there are any local standard user accounts already, the **Create an account** dialog offers the option to **Choose an existing account**
1. Choose the application to run when the kiosk account signs in. Only apps that can run above the lock screen are available in the list of apps to choose from. If you select **Microsoft Edge** as the kiosk app, you configure the following options:
- Whether Microsoft Edge should display your website full-screen (digital sign) or with some browser controls available (public browser)
- Which URL should be open when the kiosk accounts signs in
- When Microsoft Edge should restart after a period of inactivity (if you select to run as a public browser)
1. Select **Close**
When the device isn't joined to an Active Directory domain or Microsoft Entra ID, automatic sign-in of the kiosk account is configured automatically:
- If you want the kiosk account to sign in automatically, and the kiosk app launched when the device restarts, then you don't need to do anything
- If you don't want the kiosk account to sign in automatically when the device restarts, then you must change the default setting before you configure the device as a kiosk. Sign in with the account that you want to use as the kiosk account. Open **Settings** > **Accounts** > **Sign-in options**. Set the **Use my sign-in info to automatically finish setting up my device after an update or restart** setting to **Off**. After you change the setting, you can apply the kiosk configuration to the device
---
> [!TIP]
> For practical examples, see the [Quickstart: Configure a kiosk with Assigned Access](quickstart-kiosk.md).
## Configure a restricted user experience
To configure a restricted user experience with Assigned Access, you must create an XML configuration file with the settings for the desired experience. The XML file is applied to the device via the [Assigned Access CSP](/windows/client-management/mdm/assignedaccess-csp#shelllauncher), using one of the following options:
- A Mobile Device Management (MDM) solution, like Microsoft Intune
- Provisioning packages
- PowerShell, with the MDM Bridge WMI Provider
To learn how to configure the Assigned Access XML file, see [Create an Assigned Access configuration file](configuration-file.md).
[!INCLUDE [tab-intro](../../../includes/configure/tab-intro.md)]
#### [:::image type="icon" source="../images/icons/intune.svg"::: **Intune/CSP**](#tab/intune)
You can configure devices using a [custom policy][MEM-1] with the [AssignedAccess CSP][WIN-3].
- **Setting:** `./Vendor/MSFT/AssignedAccess/ShellLauncher`
- **Value:** content of the XML configuration file
Assign the policy to a group that contains as members the devices that you want to configure.
#### [:::image type="icon" source="../images/icons/provisioning-package.svg"::: **PPKG**](#tab/ppkg)
[!INCLUDE [provisioning-package-1](../../../includes/configure/provisioning-package-1.md)]
- **Path:** `AssignedAccess/MultiAppAssignedAccessSettings`
- **Value:** content of the XML configuration file
[!INCLUDE [provisioning-package-2](../../../includes/configure/provisioning-package-2.md)]
#### [:::image type="icon" source="../images/icons/powershell.svg"::: **PowerShell**](#tab/ps)
[!INCLUDE [powershell-wmi-bridge-1](../../../includes/configure/powershell-wmi-bridge-1.md)]
```PowerShell
$assignedAccessConfiguration = @"
# content of the XML configuration file
"@
$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.Configuration = [System.Net.WebUtility]::HtmlEncode($assignedAccessConfiguration)
$obj = Set-CimInstance -CimInstance $obj -ErrorVariable cimSetError -ErrorAction SilentlyContinue
if($cimSetError) {
Write-Output "An ERROR occurred. Displaying error record and attempting to retrieve error logs...`n"
Write-Error -ErrorRecord $cimSetError[0]
$timeout = New-TimeSpan -Seconds 30
$stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
do{
$events = Get-WinEvent -FilterHashtable $eventLogFilterHashTable -ErrorAction Ignore
} until ($events.Count -or $stopwatch.Elapsed -gt $timeout) # wait for the log to be available
if($events.Count) {
$events | ForEach-Object {
Write-Output "$($_.TimeCreated) [$($_.LevelDisplayName.ToUpper())] $($_.Message -replace "`n|`r")"
}
} else {
Write-Warning "Timed-out attempting to retrieve event logs..."
}
Exit 1
}
Write-Output "Successfully applied Assigned Access configuration"
```
[!INCLUDE [powershell-wmi-bridge-2](../../../includes/configure/powershell-wmi-bridge-2.md)]
#### [:::image type="icon" source="../images/icons/settings-app.svg"::: **Settings**](#tab/settings)
This option isn't available using Settings.
---
> [!TIP]
> For practical examples, see the [Quickstart: Configure a restricted user experience with Assigned Access](quickstart-restricted-user-experience.md)
## User experience
To validate the kiosk or restricted user experience, sign in with the user account you specified in the configuration file.
The Assigned Access configuration takes effect the next time the targeted user signs in. If that user account is signed in when you apply the configuration, sign out and sign back in to validate the experience.
> [!NOTE]
> Starting in Windows 11, a restricted user experience supports the use of multiple monitors.
### Autotrigger touch keyboard
The touch keyboard is automatically triggered when there's an input needed and no physical keyboard is attached on touch-enabled devices. You don't need to configure any other setting to enforce this behavior.
> [!TIP]
> The touch keyboard is triggered only when tapping a textbox. Mouse clicks don't trigger the touch keyboard. If you're testing this feature, use a physical device instead of a virtual machine (VM), as the touch keyboard is not triggered on VMs.
### Sign out of assigned access
By default, to exit the kiosk experience, press <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Del</kbd>. The kiosk app exits automatically. If you sign in again as the Assigned Access account, or wait for the sign in screen timeout, the kiosk app relaunches. The default timeout is 30 seconds, but you can change the timeout with the registry key:
`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\LogonUI`
To change the default time for Assigned Access to resume, add *IdleTimeOut* (DWORD) and enter the value data as milliseconds in hexadecimal.
> [!NOTE]
> `IdleTimeOut` doesn't apply to the Microsoft Edge kiosk mode.
The Breakout Sequence of <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Del</kbd> is the default, but this sequence can be configured to be a different sequence of keys. The breakout sequence uses the format **modifiers + keys**. An example breakout sequence is <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>A</kbd>, where <kbd>CTRL</kbd> + <kbd>ALT</kbd> are the modifiers, and <kbd>A</kbd> is the key value. To learn more, see [Create an Assigned Access configuration XML file](configuration-file.md).
## Remove Assigned Access
Deleting the restricted user experience removes the policy settings associated with the users, but it can't revert all the configurations. For example, the Start menu configuration is maintained.
## Next steps
In the next sections, you can learn more about the options available to configure kiosks and restricted user experiences:
> [!div class="nextstepaction"]
> Review the recommendations before you deploy Assigned Access:
>
> [Assigned Access recommendations](recommendations.md)
- [Assigned Access](overview.md)
- [Shell Launcher](shell-launcher/index.md)
<!--links-->
### :::image type="icon" source="../images/icons/rocket.svg" border="false"::: Quickstarts
If you're ready to try out the options available to configure kiosks and restricted user experiences, check out the following quickstarts:
- [Quickstart: configure a kiosk with Assigned Access](quickstart-kiosk.md)
- [Quickstart: configure a kiosk experience with Shell Launcher](shell-launcher/quickstart-kiosk.md)
- [Quickstart: configure a restricted user experience with Assigned Access](quickstart-restricted-user-experience.md)
[MEM-1]: /mem/intune/configuration/custom-settings-windows-10
[WIN-3]: /windows/client-management/mdm/assignedaccess-csp

315
windows/configuration/assigned-access/overview.md
View File

@ -1,315 +0,0 @@
---
title: What is Assigned Access?
description: Learn how to configure a Windows kiosk for single-app and multi-app scenarios with Assigned Access.
ms.date: 10/31/2024
ms.topic: overview
---
# What is Assigned Access?
Assigned Access is a Windows feature that you can use to configure a device as a kiosk or with a restricted user experience.
When you configure a **kiosk experience**, a single Universal Windows Platform (UWP) application or Microsoft Edge is executed in full screen, above the lock screen. Users can only use that application. If the kiosk app is closed, it automatically restarts. Practical examples include:
- Public browsing
- Interactive digital signage
When you configure a **restricted user experience**, users can only execute a defined list of applications, with a tailored Start menu and Taskbar. Different policy settings and AppLocker rules are enforced, creating a locked down experience. The users can access a familiar Windows desktop, while limiting their access, reducing distractions, and potential for inadvertent uses. Ideal for shared devices, you can create different configurations for different users. Practical examples include:
- Frontline worker devices
- Student devices
- Lab devices
> [!NOTE]
> When you configure a restricted user experience, different policy settings are applied to the device. Some policy settings apply to standard users only, and some to administrator accounts too. For more information, see [Assigned Access policy settings](policy-settings.md).
## Requirements
Here are the requirements for Assigned Access:
- To use a kiosk experience, [User account control (UAC)](/windows/security/identity-protection/user-account-control/user-account-control-overview) must be enabled
- To use a kiosk experience, you must sign in from the console. The kiosk experience isn't supported over a remote desktop connection
[!INCLUDE [assigned-access](../../../includes/licensing/assigned-access.md)]
## Configure a kiosk experience
There are several options to configure a kiosk experience. If you need to configure a single device with a local account, you can use:
- PowerShell: you can use the `Set-AssignedAccess` PowerShell cmdlet to configure a kiosk experience using a local standard account
- Settings: use this option when you need a simple method to configure a single device with a local standard user account
For advanced customizations, you can use the [Assigned Access CSP](/windows/client-management/mdm/assignedaccess-csp) to configure the kiosk experience. The CSP allows you to configure the kiosk app, the user account, and the kiosk app's behavior. When you use the CSP, you must create an XML configuration file that specifies the kiosk app and the user account. The XML file is applied to the device using one of the following options:
- A Mobile Device Management (MDM) solution, like Microsoft Intune
- Provisioning packages
- PowerShell, with the MDM Bridge WMI Provider
To learn how to configure the Shell Launcher XML file, see [Create an Assigned Access configuration file](configuration-file.md).
[!INCLUDE [tab-intro](../../../includes/configure/tab-intro.md)]
#### [:::image type="icon" source="../images/icons/intune.svg"::: **Intune/CSP**](#tab/intune)
You can configure devices using a [custom policy][MEM-1] with the [AssignedAccess CSP][WIN-3].
- **Setting:** `./Vendor/MSFT/AssignedAccess/Configuration`
- **Value:** content of the XML configuration file
Assign the policy to a group that contains as members the devices that you want to configure.
#### [:::image type="icon" source="../images/icons/provisioning-package.svg"::: **PPKG**](#tab/ppkg)
[!INCLUDE [provisioning-package-1](../../../includes/configure/provisioning-package-1.md)]
- **Path:** `AssignedAccess/AssignedAccessSettings`
- **Value:** Enter the account and the application you want to use for Assigned access, using the AUMID of the app. Example:
- `{"Account":"domain\user", "AUMID":"Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"}`
[!INCLUDE [provisioning-package-2](../../../includes/configure/provisioning-package-2.md)]
#### [:::image type="icon" source="../images/icons/powershell.svg"::: **PowerShell**](#tab/ps)
To configure a device using Windows PowerShell:
1. Sign in as administrator
1. [Create the user account](https://support.microsoft.com/help/4026923/windows-create-a-local-user-or-administrator-account-in-windows-10) for Assigned Access
1. Sign in as the Assigned Access user account
1. Install the required UWP app
1. Sign out as the Assigned Access user account
1. Sign in as administrator and from an elevated PowerShell prompt use one of the following commands:
```PowerShell
#Configure Assigned Access by AppUserModelID and user name
Set-AssignedAccess -AppUserModelId <AUMID> -UserName <username>
#Configure Assigned Access by AppUserModelID and user SID
Set-AssignedAccess -AppUserModelId <AUMID> -UserSID <usersid>
#Configure Assigned Access by app name and user name
Set-AssignedAccess -AppName <CustomApp> -UserName <username>
#Configure Assigned Access by app name and user SID**:
Set-AssignedAccess -AppName <CustomApp> -UserSID <usersid>
> [!NOTE]
> To set up Assigned Access using `-AppName`, the user account that you enter for Assigned Access must have signed in at least once.
For more information:
- [Find the Application User Model ID of an installed app](../store/find-aumid.md)
- [Set-AssignedAccess](/powershell/module/assignedaccess/set-assignedaccess)
To remove assigned access, using PowerShell, run the following cmdlet:
```powershell
Clear-AssignedAccess
```
For advanced customizations that use the XML configuration file, you can use PowerShell scripts via the [MDM Bridge WMI Provider](/windows/win32/dmwmibridgeprov/mdm-bridge-wmi-provider-portal).
> [!IMPORTANT]
> For all device settings, the WMI Bridge client must be executed as SYSTEM (LocalSystem) account.
To test the PowerShell script, you can:
1. [Download the psexec tool](/sysinternals/downloads/psexec)
1. Open an elevated command prompt and run: `psexec.exe -i -s powershell.exe`
1. Run the script in the PowerShell session
```PowerShell
$shellLauncherConfiguration = @"
# content of the XML configuration file
"@
$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.ShellLauncher = [System.Net.WebUtility]::HtmlEncode($shellLauncherConfiguration)
$obj = Set-CimInstance -CimInstance $obj -ErrorVariable cimSetError -ErrorAction SilentlyContinue
if($cimSetError) {
Write-Output "An ERROR occurred. Displaying error record and attempting to retrieve error logs...`n"
Write-Error -ErrorRecord $cimSetError[0]
$timeout = New-TimeSpan -Seconds 30
$stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
do{
$events = Get-WinEvent -FilterHashtable $eventLogFilterHashTable -ErrorAction Ignore
} until ($events.Count -or $stopwatch.Elapsed -gt $timeout) # wait for the log to be available
if($events.Count) {
$events | ForEach-Object {
Write-Output "$($_.TimeCreated) [$($_.LevelDisplayName.ToUpper())] $($_.Message -replace "`n|`r")"
}
} else {
Write-Warning "Timed-out attempting to retrieve event logs..."
}
Exit 1
}
Write-Output "Successfully applied Shell Launcher configuration"
```
[!INCLUDE [powershell-wmi-bridge-2](../../../includes/configure/powershell-wmi-bridge-2.md)]
#### [:::image type="icon" source="../images/icons/settings-app.svg"::: **Settings**](#tab/settings)
Here are the steps to configure a kiosk using the Settings app:
1. Open the Settings app to view and configure a device as a kiosk. Go to **Settings > Accounts > Other Users**, or use the following shortcut:
> [!div class="nextstepaction"]
>
> [Other Users](ms-settings:otherusers)
1. Under **Set up a kiosk**, select **Get Started**
1. In the **Create an account** dialog, enter the account name, and select **Next**
>[!NOTE]
>If there are any local standard user accounts already, the **Create an account** dialog offers the option to **Choose an existing account**
1. Choose the application to run when the kiosk account signs in. Only apps that can run above the lock screen are available in the list of apps to choose from. If you select **Microsoft Edge** as the kiosk app, you configure the following options:
- Whether Microsoft Edge should display your website full-screen (digital sign) or with some browser controls available (public browser)
- Which URL should be open when the kiosk accounts signs in
- When Microsoft Edge should restart after a period of inactivity (if you select to run as a public browser)
1. Select **Close**
When the device isn't joined to an Active Directory domain or Microsoft Entra ID, automatic sign-in of the kiosk account is configured automatically:
- If you want the kiosk account to sign in automatically, and the kiosk app launched when the device restarts, then you don't need to do anything
- If you don't want the kiosk account to sign in automatically when the device restarts, then you must change the default setting before you configure the device as a kiosk. Sign in with the account that you want to use as the kiosk account. Open **Settings** > **Accounts** > **Sign-in options**. Set the **Use my sign-in info to automatically finish setting up my device after an update or restart** setting to **Off**. After you change the setting, you can apply the kiosk configuration to the device
---
> [!TIP]
> For practical examples, see the [Quickstart: Configure a kiosk with Assigned Access](quickstart-kiosk.md).
## Configure a restricted user experience
To configure a restricted user experience with Assigned Access, you must create an XML configuration file with the settings for the desired experience. The XML file is applied to the device via the [Assigned Access CSP](/windows/client-management/mdm/assignedaccess-csp#shelllauncher), using one of the following options:
- A Mobile Device Management (MDM) solution, like Microsoft Intune
- Provisioning packages
- PowerShell, with the MDM Bridge WMI Provider
To learn how to configure the Assigned Access XML file, see [Create an Assigned Access configuration file](configuration-file.md).
[!INCLUDE [tab-intro](../../../includes/configure/tab-intro.md)]
#### [:::image type="icon" source="../images/icons/intune.svg"::: **Intune/CSP**](#tab/intune)
You can configure devices using a [custom policy][MEM-1] with the [AssignedAccess CSP][WIN-3].
- **Setting:** `./Vendor/MSFT/AssignedAccess/ShellLauncher`
- **Value:** content of the XML configuration file
Assign the policy to a group that contains as members the devices that you want to configure.
#### [:::image type="icon" source="../images/icons/provisioning-package.svg"::: **PPKG**](#tab/ppkg)
[!INCLUDE [provisioning-package-1](../../../includes/configure/provisioning-package-1.md)]
- **Path:** `AssignedAccess/MultiAppAssignedAccessSettings`
- **Value:** content of the XML configuration file
[!INCLUDE [provisioning-package-2](../../../includes/configure/provisioning-package-2.md)]
#### [:::image type="icon" source="../images/icons/powershell.svg"::: **PowerShell**](#tab/ps)
[!INCLUDE [powershell-wmi-bridge-1](../../../includes/configure/powershell-wmi-bridge-1.md)]
```PowerShell
$assignedAccessConfiguration = @"
# content of the XML configuration file
"@
$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.Configuration = [System.Net.WebUtility]::HtmlEncode($assignedAccessConfiguration)
$obj = Set-CimInstance -CimInstance $obj -ErrorVariable cimSetError -ErrorAction SilentlyContinue
if($cimSetError) {
Write-Output "An ERROR occurred. Displaying error record and attempting to retrieve error logs...`n"
Write-Error -ErrorRecord $cimSetError[0]
$timeout = New-TimeSpan -Seconds 30
$stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
do{
$events = Get-WinEvent -FilterHashtable $eventLogFilterHashTable -ErrorAction Ignore
} until ($events.Count -or $stopwatch.Elapsed -gt $timeout) # wait for the log to be available
if($events.Count) {
$events | ForEach-Object {
Write-Output "$($_.TimeCreated) [$($_.LevelDisplayName.ToUpper())] $($_.Message -replace "`n|`r")"
}
} else {
Write-Warning "Timed-out attempting to retrieve event logs..."
}
Exit 1
}
Write-Output "Successfully applied Assigned Access configuration"
```
[!INCLUDE [powershell-wmi-bridge-2](../../../includes/configure/powershell-wmi-bridge-2.md)]
#### [:::image type="icon" source="../images/icons/settings-app.svg"::: **Settings**](#tab/settings)
This option isn't available using Settings.
---
> [!TIP]
> For practical examples, see the [Quickstart: Configure a restricted user experience with Assigned Access](quickstart-restricted-user-experience.md)
## User experience
To validate the kiosk or restricted user experience, sign in with the user account you specified in the configuration file.
The Assigned Access configuration takes effect the next time the targeted user signs in. If that user account is signed in when you apply the configuration, sign out and sign back in to validate the experience.
> [!NOTE]
> Starting in Windows 11, a restricted user experience supports the use of multiple monitors.
### Autotrigger touch keyboard
The touch keyboard is automatically triggered when there's an input needed and no physical keyboard is attached on touch-enabled devices. You don't need to configure any other setting to enforce this behavior.
> [!TIP]
> The touch keyboard is triggered only when tapping a textbox. Mouse clicks don't trigger the touch keyboard. If you're testing this feature, use a physical device instead of a virtual machine (VM), as the touch keyboard is not triggered on VMs.
### Sign out of assigned access
By default, to exit the kiosk experience, press <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Del</kbd>. The kiosk app exits automatically. If you sign in again as the Assigned Access account, or wait for the sign in screen timeout, the kiosk app relaunches. The default timeout is 30 seconds, but you can change the timeout with the registry key:
`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\LogonUI`
To change the default time for Assigned Access to resume, add *IdleTimeOut* (DWORD) and enter the value data as milliseconds in hexadecimal.
> [!NOTE]
> `IdleTimeOut` doesn't apply to the Microsoft Edge kiosk mode.
The Breakout Sequence of <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Del</kbd> is the default, but this sequence can be configured to be a different sequence of keys. The breakout sequence uses the format **modifiers + keys**. An example breakout sequence is <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>A</kbd>, where <kbd>CTRL</kbd> + <kbd>ALT</kbd> are the modifiers, and <kbd>A</kbd> is the key value. To learn more, see [Create an Assigned Access configuration XML file](configuration-file.md).
## Remove Assigned Access
Deleting the restricted user experience removes the policy settings associated with the users, but it can't revert all the configurations. For example, the Start menu configuration is maintained.
## Next steps
> [!div class="nextstepaction"]
> Review the recommendations before you deploy Assigned Access:
>
> [Assigned Access recommendations](recommendations.md)
<!--links-->
[MEM-1]: /mem/intune/configuration/custom-settings-windows-10
[WIN-3]: /windows/client-management/mdm/assignedaccess-csp

131
windows/configuration/assigned-access/shell-launcher/index.md
View File

@ -1,131 +0,0 @@
---
title: What is Shell Launcher?
description: Learn how to configure devices with Shell Launcher.
ms.date: 10/31/2024
ms.topic: overview
---
# What is Shell Launcher?
Shell Launcher is a Windows feature that you can use to replace the default Windows Explorer shell (`Explorer.exe`) with a Windows desktop application or a Universal Windows Platform (UWP) app.
Practical examples include:
- Public browsing
- Interactive digital signage
- ATMs
Shell Launcher controls which application the user sees as the shell after sign-in. It doesn't prevent the user from accessing other desktop applications and system components. From a custom shell, you can launch secondary views displayed on multiple monitors, or launch other apps in full screen on user's demand.
With Shell Launcher, you can use features and methods to control access to other applications or system components. These methods include, but aren't limited to:
- Configuration Service Provider (CSP): you can use a Mobile Device Management (MDM) solution like Microsoft Intune
- Group policy (GPO)
- [AppLocker](/windows/security/threat-protection/windows-defender-application-control/applocker/applocker-overview)
Shell Launcher is part of the [Assigned Access](../overview.md) feature, which allows you to configure kiosks or restricted user experiences. To learn about the differences between Shell Launcher and the other options offered by Assigned Access, see [Windows kiosks and restricted user experiences](../index.md).
[!INCLUDE [shell-launcher](../../../../includes/licensing/shell-launcher.md)]
## Limitations
Here are some limitations to consider when using Shell Launcher:
- Windows doesn't support setting a custom shell before the out-of-box experience (OOBE). If you do, you can't deploy the resulting image
- Shell Launcher doesn't support a custom shell with an application that launches a different process and exits. For example, you can't specify `write.exe` in Shell Launcher. Shell Launcher launches a custom shell and monitors the process to identify when the custom shell exits. `Write.exe` creates a 32-bit `wordpad.exe` process and exits. Since Shell Launcher isn't aware of the newly created `wordpad.exe` process, Shell Launcher takes action based on the exit code of `Write.exe`, such as restarting the custom shell
## Configure a device with Shell Launcher
The configuration of Shell Launcher is done using an XML file. The XML file is applied to the device via the [Assigned Access CSP](/windows/client-management/mdm/assignedaccess-csp#shelllauncher), using one of the following options:
- A Mobile Device Management (MDM) solution, like Microsoft Intune
- Provisioning packages
- The MDM Bridge WMI Provider
To learn how to configure the Shell Launcher XML file, see [Create a Shell Launcher configuration file](configuration-file.md).
[!INCLUDE [tab-intro](../../../../includes/configure/tab-intro.md)]
#### [:::image type="icon" source="../../images/icons/intune.svg"::: **Intune/CSP**](#tab/intune)
You can configure devices using a [custom policy][MEM-1] with the [AssignedAccess CSP][WIN-3].
- **Setting:** `./Vendor/MSFT/AssignedAccess/ShellLauncher`
- **Value:** content of the XML configuration file
Assign the policy to a group that contains as members the devices that you want to configure.
#### [:::image type="icon" source="../../images/icons/provisioning-package.svg"::: **PPKG**](#tab/ppkg)
[!INCLUDE [provisioning-package-1](../../../../includes/configure/provisioning-package-1.md)]
- **Path:** `SMISettings/ShellLauncher`
- **Value:** depends on specific settings
[!INCLUDE [provisioning-package-2](../../../../includes/configure/provisioning-package-2.md)]
#### [:::image type="icon" source="../../images/icons/powershell.svg"::: **PowerShell**](#tab/ps)
[!INCLUDE [powershell-wmi-bridge-1](../../../../includes/configure/powershell-wmi-bridge-1.md)]
```PowerShell
$shellLauncherConfiguration = @"
# content of the XML configuration file
"@
$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.ShellLauncher = [System.Net.WebUtility]::HtmlEncode($shellLauncherConfiguration)
$obj = Set-CimInstance -CimInstance $obj -ErrorVariable cimSetError -ErrorAction SilentlyContinue
if($cimSetError) {
Write-Output "An ERROR occurred. Displaying error record and attempting to retrieve error logs...`n"
Write-Error -ErrorRecord $cimSetError[0]
$timeout = New-TimeSpan -Seconds 30
$stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
$eventLogFilterHashTable = @{ LogName='Microsoft-Windows-AssignedAccess/Admin' }
do{
$events = Get-WinEvent -FilterHashtable $eventLogFilterHashTable -ErrorAction Ignore
} until ($events.Count -or $stopwatch.Elapsed -gt $timeout) # wait for the log to be available
if($events.Count) {
$events | ForEach-Object {
Write-Output "$($_.TimeCreated) [$($_.LevelDisplayName.ToUpper())] $($_.Message -replace "`n|`r")"
}
} else {
Write-Warning "Timed-out attempting to retrieve event logs..."
}
Exit 1
}
Write-Output "Successfully applied Shell Launcher configuration"
```
[!INCLUDE [powershell-wmi-bridge-2](../../../../includes/configure/powershell-wmi-bridge-2.md)]
---
> [!TIP]
> For practical examples, see the [Quickstart: configure a kiosk experience with Shell Launcher](quickstart-kiosk.md).
## User experience
After the settings are applied, the users that are configured to use Shell Launcher will execute the custom shell after sign-in.
Depending on your configuration, you can have a user to automatically sign in to the device.
## Next steps
> [!div class="nextstepaction"]
> Learn how to configure the Shell Launcher XML file:
>
> [Create a Shell Launcher configuration file](configuration-file.md)
<!--links-->
[MEM-1]: /mem/intune/configuration/custom-settings-windows-10
[WIN-3]: /windows/client-management/mdm/assignedaccess-csp

9
windows/configuration/assigned-access/shell-launcher/toc.yml
View File

@ -1,9 +0,0 @@
items:
- name: What is Shell Launcher?
href: index.md
- name: "Quickstart: Configure a kiosk with Shell Launcher"
href: quickstart-kiosk.md
- name: Create a Shell Launcher configuration file
href: configuration-file.md
- name: Shell Launcher XSD
href: xsd.md

14
windows/configuration/assigned-access/toc.yml
View File

@ -1,18 +1,16 @@
items:
- name: Overview
href: index.md
- name: Assigned Access
items:
- name: What is Assigned Access?
href: overview.md
href: index.md
- name: Create an Assigned Access configuration file
href: configuration-file.md
- name: Quickstarts
items:
- name: Configure a kiosk with Assigned Access
href: quickstart-kiosk.md
- name: Configure a restricted user experience with Assigned Access
href: quickstart-restricted-user-experience.md
- name: Create an Assigned Access configuration file
href: configuration-file.md
- name: Reference
items:
- name: Assigned Access XSD
@ -21,13 +19,7 @@ items:
href: examples.md
- name: Assigned Access policy settings
href: policy-settings.md
- name: Shell Launcher
href: shell-launcher/toc.yml
- name: Recommendations
href: recommendations.md
- name: Assigned Access CSP 🔗
href: /windows/client-management/mdm/assignedaccess-csp
- name: Troubleshoot 🔗
href: /troubleshoot/windows-client/shell-experience/kiosk-mode-issues-troubleshooting
- name: Configure Microsoft Edge kiosk mode 🔗
href: /deployedge/microsoft-edge-configure-kiosk-mode

BIN
windows/configuration/kiosk/images/kiosk.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

BIN
windows/configuration/kiosk/images/restricted-user-experience-example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 763 KiB

BIN
windows/configuration/kiosk/images/restricted-user-experience.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.4 KiB

74
windows/configuration/kiosk/index.md Normal file
View File

@ -0,0 +1,74 @@
---
title: Windows kiosks and restricted user experiences
description: Learn about the options available in Windows to configure kiosks and restricted user experiences.
ms.topic: overview
ms.date: 10/31/2024
---
# Windows kiosks and restricted user experiences
Organizations are constantly seeking ways to streamline operations, improve customer service, and enhance productivity. One effective solution is the deployment of kiosk devices. These specialized devices offer a range of benefits that can significantly impact an organization's efficiency and success. For example:
- Cost-effective customer service: kiosks allow organizations to provide essential services without the need for dedicated staff. Whether it's checking in at a hotel, ordering food at a restaurant, or printing boarding passes at an airport, kiosks reduce labor costs while maintaining service quality. Customers appreciate the convenience of self-service options, leading to higher satisfaction levels
- Reduced wait times: long queues and wait times frustrate customers and staff members. Kiosks expedite processes by allowing users to complete tasks independently. Whether it's paying bills, renewing memberships, or accessing information, kiosks empower users to get things done swiftly
- Consistent brand experience: kiosks ensure a uniform brand experience across different locations. Whether in retail stores, schools, airports, or healthcare facilities, the interface remains consistent. Brand consistency builds trust and reinforces the organization's image
- Customization and flexibility: kiosks can be tailored to specific needs. From touchscreens to barcode scanners, organizations choose features that align with their goals. Whether it's self-checkout, wayfinding, or interactive product catalogs, kiosks adapt to diverse requirements
Windows offers two different options for public or specialized use:
:::row:::
:::column span="1":::
:::image type="content" source="images/kiosk.png" alt-text="Icon representing a kiosk." border="false":::
:::column-end:::
:::column span="3":::
#### Kiosk experience
:::column-end:::
:::row-end:::
This option runs a single application in full screen, and people using the device can only use that app. When the designated kiosk account signs in, the kiosk app launches automatically. This option is sometimes referred to as *single-app kiosk*.
Windows offers two different features to configure a kiosk experience:
- **Assigned Access**: used to execute a single Universal Windows Platform (UWP) app or Microsoft Edge in full screen above the lock screen. When the kiosk account signs in, the kiosk app launches automatically. If the UWP app is closed, it automatically restarts
- **Shell Launcher**: used to configure a device to execute a Windows desktop application as the user interface. The application that you specify replaces the default Windows shell (`Explorer.exe`) that usually runs when a user signs in. This type of single-app kiosk doesn't run above the lock screen
:::row:::
:::column span="1":::
:::image type="content" source="images/restricted-user-experience.png" alt-text="Icon representing a restricted user experience." border="false":::
:::column-end:::
:::column span="3":::
#### Restricted user experience
:::column-end:::
:::row-end:::
This option loads the Windows desktop, but it only allows to run a defined set of applications. When the designated user signs in, the user can only run the apps that are allowed. The Start menu is customized to show only the apps that are allowed to execute. With this approach, you can configure a locked-down experience for different account types. This option is sometimes referred to as *multi-app kiosk*.
:::image type="content" source="images/restricted-user-experience-example.png" alt-text="Screenshot of a restricted user experience in Windows 11." border="false":::
To configure a restricted user experience, you use the **Assigned Access** feature.
## Choose the right experience
When you're considering a kiosk or restricted user experience, you need to choose the right experience for your needs. A good approach is to ask yourself the following set of questions:
| | Question |
|--|--|
| **🔲** | *How many apps?* <br>The number of apps determines the experience to build: **kiosk** or **restricted user experience**.|
| **🔲** | *Desktop experience or custom?* <br>If your users require access to the desktop with a custom Start menu, then you can build a **restricted user experience** with **Assigned Access**. If your users require access to multiple applications but with a custom user interface, then you should use **Shell Launcher**.|
| **🔲** | *In single-app scenario, which type of app will your kiosk run?* <br>If the kiosk requires a Universal Windows Platform (UWP) app or Microsoft Edge, you can build a **kiosk experience** with **Assigned Access**. If the kiosk requires a desktop app, you can build a **kiosk experience** with **Shell Launcher**.|
| **🔲** | *Which edition of Windows client will the kiosk run?"* <br>**Assigned Access** is supported on Windows Pro and Enterprise/Education. **Shell Launcher** is only supported on Windows Enterprise and Education editions.|
## Next steps
Learn more about the options available to configure kiosks and restricted user experiences:
- [Assigned Access](../assigned-access/index.md)
- [Shell Launcher](../shell-launcher/index.md)
### :::image type="icon" source="../images/icons/rocket.svg" border="false"::: Quickstarts
If you're ready to try out the options available to configure kiosks and restricted user experiences, check out the following quickstarts:
- [Quickstart: configure a kiosk with Assigned Access](../assigned-access/quickstart-kiosk.md)
- [Quickstart: configure a kiosk experience with Shell Launcher](../shell-launcher/quickstart-kiosk.md)
- [Quickstart: configure a restricted user experience with Assigned Access](../assigned-access/quickstart-restricted-user-experience.md)

13
windows/configuration/kiosk/toc.yml Normal file
View File

@ -0,0 +1,13 @@
items:
- name: Overview
href: index.md
- name: Assigned Access
items:
- name: What is Assigned Access?
href: ../assigned-access/toc.yml
- name: Shell Launcher
href: ../shell-launcher/toc.yml
- name: Troubleshoot 🔗
href: /troubleshoot/windows-client/shell-experience/kiosk-mode-issues-troubleshooting
- name: Configure Microsoft Edge kiosk mode 🔗
href: /deployedge/microsoft-edge-configure-kiosk-mode

0
windows/configuration/shell-launcher/browser-support.md → windows/configuration/shell-launcher/browser-support_old.md
View File

0
windows/configuration/assigned-access/shell-launcher/configuration-file.md → windows/configuration/shell-launcher/configuration-file.md
View File

0
windows/configuration/assigned-access/shell-launcher/includes/quickstart-intune.md → windows/configuration/shell-launcher/includes/quickstart-intune.md
View File

0
windows/configuration/assigned-access/shell-launcher/includes/quickstart-ps.md → windows/configuration/shell-launcher/includes/quickstart-ps.md
View File

0
windows/configuration/assigned-access/shell-launcher/includes/quickstart-xml.md → windows/configuration/shell-launcher/includes/quickstart-xml.md
View File

379
windows/configuration/shell-launcher/index.md
View File

@ -1,344 +1,131 @@
---
title: Shell Launcher
description: Shell Launcher
ms.date: 06/07/2018
title: What is Shell Launcher?
description: Learn how to configure devices with Shell Launcher.
ms.date: 10/31/2024
ms.topic: overview
---
# Shell Launcher
# What is Shell Launcher?
Using Shell Launcher, you can configure a kiosk device to use almost any application or executable as your custom shell. The application that you specify replaces the default shell (explorer.exe) that usually runs when a user logs on.
Shell Launcher is a Windows feature that you can use to replace the default Windows Explorer shell (`Explorer.exe`) with a Windows desktop application or a Universal Windows Platform (UWP) app.
You can also configure Shell Launcher to launch different shell applications for different users or user groups.
Practical examples include:
There are a few exceptions to the applications and executables you can use as a custom shell:
- Public browsing
- Interactive digital signage
- ATMs
- You can't use the following executable as a custom shell: `C:\\Windows\\System32\\Eshell.exe`. Using Eshell.exe as the default shell will result in a blank screen after user signs in.
- You can't use a Universal Windows app as a custom shell.
- You can't use a custom shell to launch Universal Windows apps, for example, the Settings app.
- You can't use an application that launches a different process and exits as a custom shell. For example, you can't specify **write.exe** in Shell Launcher. Shell Launcher launches a custom shell and monitors the process to identify when the custom shell exits. **Write.exe** creates a 32-bit wordpad.exe process and exits. Because Shell Launcher isn't aware of the newly created wordpad.exe process, Shell Launcher takes action based on the exit code of **Write.exe**, and restart the custom shell.
- You can't prevent the system from shutting down. For Shell Launcher V1 and V2, you can't block the session ending by returning FALSE upon receiving the [WM_QUERYENDSESSION](/windows/win32/shutdown/wm-queryendsession) message in a graphical application or returning FALSE in the [handler routine](/windows/console/handlerroutine) that is added through the [SetConsoleCtrlHandler](/windows/console/setconsolectrlhandler) function in a console application.
Shell Launcher controls which application the user sees as the shell after sign-in. It doesn't prevent the user from accessing other desktop applications and system components. From a custom shell, you can launch secondary views displayed on multiple monitors, or launch other apps in full screen on user's demand.
> [!NOTE]
> You cannot configure both Shell Launcher and assigned access on the same system.
>
> Use **Shell Launcher V2**, you can specify a Universal Windows app as a custom shell. Check [Use Shell Launcher to create a Windows 10 kiosk](/windows/configuration/kiosk-shelllauncher) for the differences between Shell Launcher v1 and Shell Launcher V2.
With Shell Launcher, you can use features and methods to control access to other applications or system components. These methods include, but aren't limited to:
Shell Launcher processes the **Run** and **RunOnce** registry keys before starting the custom shell, so your custom shell doesn't need to handle the automatic startup of other applications and services.
- Configuration Service Provider (CSP): you can use a Mobile Device Management (MDM) solution like Microsoft Intune
- Group policy (GPO)
- [AppLocker](/windows/security/threat-protection/windows-defender-application-control/applocker/applocker-overview)
Shell Launcher also handles the behavior of the system when your custom shell exits. You can configure the shell exit behavior if the default behavior doesn't meet your needs.
Shell Launcher is part of the Assigned Access feature, which allows you to configure kiosks or restricted user experiences. To learn about the differences between Shell Launcher and the other options offered by Assigned Access, see [Windows kiosks and restricted user experiences](../kiosk/index.md).
Methods of controlling access to other desktop applications and system components can be used in addition to using the Shell Launcher such as, [Group Policy](https://www.microsoft.com/download/details.aspx?id=25250), [AppLocker](/windows/iot/iot-enterprise/customize/application-control#applocker), and [Mobile Device Management](/windows/client-management/mdm/)
[!INCLUDE [shell-launcher](../../../../includes/licensing/shell-launcher.md)]
> [!NOTE]
>
> In Shell Launcher v1, available in Windows 10, you can only specify a Windows desktop application as the replacement shell. In Shell Launcher v2, available in Windows 10, version 1809 and above, you can also specify a UWP app as the replacement shell.
>
> To use Shell Launcher v2 in version 1809, you need to install the [KB4551853 update](https://support.microsoft.com/topic/may-12-2020-kb4551853-os-build-17763-1217-c2ea33f7-4506-dd13-2739-d9c7bb80b26d).
## Limitations
## Differences between Shell Launcher v1 and Shell Launcher v2
Here are some limitations to consider when using Shell Launcher:
Shell Launcher v1 replaces ```explorer.exe```, the default shell, with ```eshell.exe```, which can launch a Windows desktop application.
Shell Launcher v2 replaces ```explorer.exe``` with ```customshellhost.exe```. This new executable file can launch a Windows desktop application or a UWP app.
In addition to allowing you to use a UWP app for your replacement shell, Shell Launcher v2 offers more enhancements:
- Windows doesn't support setting a custom shell before the out-of-box experience (OOBE). If you do, you can't deploy the resulting image
- Shell Launcher doesn't support a custom shell with an application that launches a different process and exits. For example, you can't specify `write.exe` in Shell Launcher. Shell Launcher launches a custom shell and monitors the process to identify when the custom shell exits. `Write.exe` creates a 32-bit `wordpad.exe` process and exits. Since Shell Launcher isn't aware of the newly created `wordpad.exe` process, Shell Launcher takes action based on the exit code of `Write.exe`, such as restarting the custom shell
- You can use a custom Windows desktop application that can then launch UWP apps, such as Settings and Touch Keyboard.
- From a custom UWP shell, you can launch secondary views and run on multiple monitors.
- The custom shell app runs in full screen, and can run other apps in full screen on user's demand.
For sample XML configurations for the different app combinations, see [Samples for Shell Launcher v2](https://github.com/microsoft/Windows-IoT-Samples/tree/master/samples/ShellLauncher/ShellLauncherV2).
## Configure a device with Shell Launcher
## Requirements
The configuration of Shell Launcher is done using an XML file. The XML file is applied to the device via the [Assigned Access CSP](/windows/client-management/mdm/assignedaccess-csp#shelllauncher), using one of the following options:
Windows 10 Enterprise or Windows 10 Education.
- A Mobile Device Management (MDM) solution, like Microsoft Intune
- Provisioning packages
- The MDM Bridge WMI Provider
## Terminology
To learn how to configure the Shell Launcher XML file, see [Create a Shell Launcher configuration file](configuration-file.md).
- **Turn on, enable:** To make the setting available to the device and optionally apply the settings to the device.
- **Configure:** To customize the setting or subsettings.
- **Embedded Shell Launcher:** This feature is called Embedded Shell Launcher in Windows 10, version 1511.
- **Custom Shell Launcher:** This feature is called Shell Launcher in Windows 10, version 1607 and later.
[!INCLUDE [tab-intro](../../../../includes/configure/tab-intro.md)]
## Turn on Shell Launcher
#### [:::image type="icon" source="../../images/icons/intune.svg"::: **Intune/CSP**](#tab/intune)
Shell Launcher is an optional component and isn't turned on by default in Windows 10. It must be turned on prior to configuring. You can turn on and configure Shell Launcher in a customized Windows 10 image (.wim) if Microsoft Windows hasn't been installed. If Windows has already been installed, you must turn on Shell Launcher before applying a provisioning package to configure Shell Launcher.
You can configure devices using a [custom policy][MEM-1] with the [AssignedAccess CSP][WIN-3].
### Enable Shell Launcher using Control Panel
- **Setting:** `./Vendor/MSFT/AssignedAccess/ShellLauncher`
- **Value:** content of the XML configuration file
1. In the **Search the web and Windows** field, type **Programs and Features** and either press **Enter** or tap or select **Programs and Features** to open it.
1. In the **Programs and Features** window, select **Turn Windows features on or off**.
1. In the **Windows Features** window, expand the **Device Lockdown** node, select or clear the checkbox for **Shell Launcher**, and then select **OK.**
1. The **Windows Features** window indicates that Windows is searching for required files and displays a progress bar. Once found, the window indicates that Windows is applying the changes. When completed, the window indicates the requested changes are completed.
1. Select **Close** to close the **Windows Features** window.
Assign the policy to a group that contains as members the devices that you want to configure.
> [!NOTE]
> Turning on Shell Launcher does not require a device restart.
#### [:::image type="icon" source="../../images/icons/provisioning-package.svg"::: **PPKG**](#tab/ppkg)
### Enable Shell Launcher by calling WESL_UserSetting
[!INCLUDE [provisioning-package-1](../../../../includes/configure/provisioning-package-1.md)]
1. Enable or disable Shell Launcher by calling the WESL_UserSetting.SetEnabled function in the Windows Management Instrumentation (WMI) class WESL_UserSetting.
1. If you enable or disable Shell Launcher using WESL_UserSetting, the changes don't affect any sessions that are currently signed in; you must sign out and sign back in.
- **Path:** `SMISettings/ShellLauncher`
- **Value:** depends on specific settings
This example uses a Windows image called install.wim, but you can use the same procedure to apply a provisioning package (for more information on DISM, see [What Is Deployment Image Servicing and Management](/windows-hardware/manufacture/desktop/what-is-dism).
[!INCLUDE [provisioning-package-2](../../../../includes/configure/provisioning-package-2.md)]
### Enable Shell Launcher using DISM
#### [:::image type="icon" source="../../images/icons/powershell.svg"::: **PowerShell**](#tab/ps)
1. Open a command prompt with administrator privileges.
1. Copy install.wim to a temporary folder on hard drive (in the following steps, we assume it's called C:\\wim).
1. Create a new directory.
```CMD
md c:\wim
```
1. Mount the image.
```CMD
dism /mount-wim /wimfile:c:\bootmedia\sources\install.wim /index:1 /MountDir:c:\wim
```
1. Enable the feature.
```CMD
dism /image:c:\wim /enable-feature /all /featureName:Client-EmbeddedShellLauncher
```
1. Commit the change.
```CMD
dism /unmount-wim /MountDir:c:\wim /Commit
```
### Enable Shell Launcher using Windows Configuration Designer
The Shell Launcher settings are also available as Windows provisioning settings so you can configure these settings to be applied during the image runtime. You can set one or all Shell Launcher settings by creating a provisioning package using Windows Configuration Designer and then applying the provisioning package during image deployment time or runtime. If Windows hasn't been installed and you're using Windows Configuration Designer to create installation media with settings for Shell Launcher included in the image or you're applying a provisioning package during setup, you must enable Shell Launcher on the installation media with DISM in order for a provisioning package to successfully apply.
Use the following steps to create a provisioning package that contains the ShellLauncher settings.
1. Build a provisioning package in Windows Configuration Designer by following the instructions in [Create a provisioning package for Windows 10](/windows/configuration/provisioning-packages/provisioning-create-package).
1. In the **Available customizations** page, select **Runtime settings** > **SMISettings** > **ShellLauncher**.
1. Set the value of **Enable** to **ENABLE**. More options to configure Shell Launcher appears, and you can set the values as desired.
1. Once you have finished configuring the settings and creating the provisioning package, you can apply the package to the image deployment time or runtime. See the [Apply a provisioning package](/windows/configuration/provisioning-packages/provisioning-apply-package) for more information. The process for applying the package to a Windows 10 Enterprise image is the same.
## Configure Shell Launcher
There are two ways you can configure Shell Launcher:
1. In Windows 10, version 1803, you can configure Shell Launcher using the **ShellLauncher** node of the Assigned Access Configuration Service Provider (CSP). See [AssignedAccess CSP](/windows/client-management/mdm/assignedaccess-csp) for details. Configuring Shell Launcher using this method also automatically enables Shell Launcher on the device, if the device supports it.
1. Use the Shell Launcher WMI providers directly in a PowerShell script or application.
You can configure the following options for Shell Launcher:
- Enable or disable Shell Launcher.
- Specify a shell configuration for a specific user or group.
- Remove a shell configuration for a specific user or group.
- Change the default shell configuration.
- Get information on a shell configuration for a specific user or group.
Any changes don't take effect until a user signs in.
## Launch different shells for different user accounts
By default, Shell Launcher runs the default shell, which is specified when you create the OS image at design time. The default shell is set to Cmd.exe, but you can specify any executable file to be the default shell.
You can configure Shell Launcher to launch a different shell for specific users or groups if you don't want to run the default shell. For example, you might configure a device to run a custom application shell for guest accounts, but run the standard Windows Explorer shell for administrator accounts in order to service the device.
If you use the WMI providers to configure Shell Launcher for a user or group at run time, you must use the security identifier (SID) for that user or group; you can't use the user name or group name.
For more information about common security identifiers, see [Well-known SIDs](/windows/win32/secauthz/well-known-sids).
When the current signed in account belongs to two or more groups that have different configurations defined for each group, Shell Launcher uses the first configuration it finds. The search order isn't defined, so we recommend that you avoid assigning a user to multiple groups with different Shell Launcher configurations.
## Perform an action when the shell exits
When a custom shell exits, Shell Launcher can perform one of four actions:
|Action|Description|
|:---:|:---|
|0|Restart the shell.|
|1|Restart the device.|
|2|Shut down the device.|
|3|Do nothing.|
> [!IMPORTANT]
> Make sure that your shell application does not automatically exit and is not automatically closed by any features such as Dialog Filter, as this can lead to an infinite cycle of exiting and restarting, unless the return code action is set to do nothing.
### Default return code action
You can define a default return code action for Shell Launcher with the DefaultReturnCodeAction setting. If you don't change the initial value, the default return code action is set to 0 (zero), which indicates that Shell Launcher restarts the shell when the shell exits.
### Map the exit code to a Shell Launcher action
Shell Launcher can take a specific action based on the exit code returned by the shell. For any given exit code returned by the shell, you can configure the action that Shell Launcher takes by mapping that exit code to one of the shell exit actions.
If the exit code doesn't match a defined value, Shell Launcher performs the default return code action.
For example, your shell might return exit code values of -1, 0, 1, or 255 depending on how the shell exits. You can configure Shell Launcher to:
- restart the device (1) when the shell returns an exit code of value -1
- restart the shell (0) when the shell returns an exit code of value 0
- do nothing (3) when the shell returns an exit code of value 1
- shut down the device (2) when the shell returns an exit code of value 255
Your custom return code action mapping would look like this:
|Exit code|Action|
|:----:|----|
|-1|1 (restart the device)|
|0|0 (restart the shell)|
|1|3 (do nothing)|
|255|2 (shut down the device)|
## Set your custom shell
Modify the following PowerShell script as appropriate and run the script on the device.
[!INCLUDE [powershell-wmi-bridge-1](../../../../includes/configure/powershell-wmi-bridge-1.md)]
```PowerShell
# Check if shell launcher license is enabled
function Check-ShellLauncherLicenseEnabled
{
[string]$source = @"
using System;
using System.Runtime.InteropServices;
$shellLauncherConfiguration = @"
static class CheckShellLauncherLicense
{
const int S_OK = 0;
# content of the XML configuration file
public static bool IsShellLauncherLicenseEnabled()
{
int enabled = 0;
if (NativeMethods.SLGetWindowsInformationDWORD("EmbeddedFeature-ShellLauncher-Enabled", out enabled) != S_OK) {
enabled = 0;
}
return (enabled != 0);
}
static class NativeMethods
{
[DllImport("Slc.dll")]
internal static extern int SLGetWindowsInformationDWORD([MarshalAs(UnmanagedType.LPWStr)]string valueName, out int value);
}
}
"@
$type = Add-Type -TypeDefinition $source -PassThru
$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.ShellLauncher = [System.Net.WebUtility]::HtmlEncode($shellLauncherConfiguration)
$obj = Set-CimInstance -CimInstance $obj -ErrorVariable cimSetError -ErrorAction SilentlyContinue
if($cimSetError) {
Write-Output "An ERROR occurred. Displaying error record and attempting to retrieve error logs...`n"
Write-Error -ErrorRecord $cimSetError[0]
return $type[0]::IsShellLauncherLicenseEnabled()
$timeout = New-TimeSpan -Seconds 30
$stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
$eventLogFilterHashTable = @{ LogName='Microsoft-Windows-AssignedAccess/Admin' }
do{
$events = Get-WinEvent -FilterHashtable $eventLogFilterHashTable -ErrorAction Ignore
} until ($events.Count -or $stopwatch.Elapsed -gt $timeout) # wait for the log to be available
if($events.Count) {
$events | ForEach-Object {
Write-Output "$($_.TimeCreated) [$($_.LevelDisplayName.ToUpper())] $($_.Message -replace "`n|`r")"
}
} else {
Write-Warning "Timed-out attempting to retrieve event logs..."
}
[bool]$result = $false
$result = Check-ShellLauncherLicenseEnabled
"`nShell Launcher license enabled is set to " + $result
if (-not($result))
{
"`nThis device doesn&#39;t have required license to use Shell Launcher"
exit
Exit 1
}
$COMPUTER = "localhost"
$NAMESPACE = "root\standardcimv2\embedded"
# Create a handle to the class instance so we can call the static methods.
try {
$ShellLauncherClass = [wmiclass]"\\$COMPUTER\${NAMESPACE}:WESL_UserSetting"
} catch [Exception] {
write-host $_.Exception.Message;
write-host "Make sure Shell Launcher feature is enabled"
exit
}
# This well-known security identifier (SID) corresponds to the BUILTIN\Administrators group.
$Admins_SID = "S-1-5-32-544"
# Create a function to retrieve the SID for a user account on a machine.
function Get-UsernameSID($AccountName) {
$NTUserObject = New-Object System.Security.Principal.NTAccount($AccountName)
$NTUserSID = $NTUserObject.Translate([System.Security.Principal.SecurityIdentifier])
return $NTUserSID.Value
}
# Get the SID for a user account named "Cashier". Rename "Cashier" to an existing account on your system to test this script.
$Cashier_SID = Get-UsernameSID("Cashier")
# Define actions to take when the shell program exits.
$restart_shell = 0
$restart_device = 1
$shutdown_device = 2
$do_nothing = 3
# Examples. You can change these examples to use the program that you want to use as the shell.
# This example sets the command prompt as the default shell, and restarts the device if the command prompt is closed.
$ShellLauncherClass.SetDefaultShell("cmd.exe", $restart_device)
# Display the default shell to verify that it was added correctly.
$DefaultShellObject = $ShellLauncherClass.GetDefaultShell()
"`nDefault Shell is set to " + $DefaultShellObject.Shell + " and the default action is set to " + $DefaultShellObject.defaultaction
# Set Internet Explorer as the shell for "Cashier", and restart the machine if Internet Explorer is closed.
$ShellLauncherClass.SetCustomShell($Cashier_SID, "c:\program files\internet explorer\iexplore.exe www.microsoft.com", ($null), ($null), $restart_shell)
# Set Explorer as the shell for administrators.
$ShellLauncherClass.SetCustomShell($Admins_SID, "explorer.exe")
# View all the custom shells defined.
"`nCurrent settings for custom shells:"
Get-WmiObject -namespace $NAMESPACE -computer $COMPUTER -class WESL_UserSetting | Select Sid, Shell, DefaultAction
# Enable Shell Launcher
$ShellLauncherClass.SetEnabled($TRUE)
$IsShellLauncherEnabled = $ShellLauncherClass.IsEnabled()
"`nEnabled is set to " + $IsShellLauncherEnabled.Enabled
# Remove the new custom shells.
$ShellLauncherClass.RemoveCustomShell($Admins_SID)
$ShellLauncherClass.RemoveCustomShell($Cashier_SID)
# Disable Shell Launcher
$ShellLauncherClass.SetEnabled($FALSE)
$IsShellLauncherEnabled = $ShellLauncherClass.IsEnabled()
"`nEnabled is set to " + $IsShellLauncherEnabled.Enabled
Write-Output "Successfully applied Shell Launcher configuration"
```
> [!NOTE]
> The previous script includes examples of multiple configuration options, including removing a custom shell and disabling Shell Launcher. It is not intended to be run as-is.
[!INCLUDE [powershell-wmi-bridge-2](../../../../includes/configure/powershell-wmi-bridge-2.md)]
## Shell Launcher user rights
---
A custom shell is launched with the same level of user rights as the account that is signed in. This means that a user with administrator rights can perform any system action that requires administrator rights, including launching other applications with administrator rights, while a user without administrator rights can't.
> [!TIP]
> For practical examples, see the [Quickstart: configure a kiosk experience with Shell Launcher](quickstart-kiosk.md).
> [!WARNING]
> If your shell application requires administrator rights and needs to be elevated, and User Account Control (UAC) is present on your device, you must disable UAC in order for Shell Launcher to launch the shell application.
## User experience
## Related articles
After the settings are applied, the users that are configured to use Shell Launcher will execute the custom shell after sign-in.
- [Unbranded Boot](../unbranded-boot/index.md)
- [Custom Logon](../custom-logon/index.md)
- [Use Shell Launcher to create a Windows 10 Kiosk](/windows/configuration/kiosk-shelllauncher)
- [Launch different shells for different user accounts](/windows-hardware/customize/enterprise/shell-launcher#launch-different-shells-for-different-user-accounts)
- [Perform an action when the shell exits](/windows-hardware/customize/enterprise/shell-launcher#perform-an-action-when-the-shell-exits)
- [Shell Launcher user rights](/windows-hardware/customize/enterprise/shell-launcher#shell-launcher-user-rights)
Depending on your configuration, you can have a user to automatically sign in to the device.
## Next steps
> [!div class="nextstepaction"]
> Learn how to configure the Shell Launcher XML file:
>
> [Create a Shell Launcher configuration file](configuration-file.md)
<!--links-->
[MEM-1]: /mem/intune/configuration/custom-settings-windows-10
[WIN-3]: /windows/client-management/mdm/assignedaccess-csp

344
windows/configuration/shell-launcher/index_old.md Normal file
View File

@ -0,0 +1,344 @@
---
title: Shell Launcher
description: Shell Launcher
ms.date: 06/07/2018
ms.topic: overview
---
# Shell Launcher
Using Shell Launcher, you can configure a kiosk device to use almost any application or executable as your custom shell. The application that you specify replaces the default shell (explorer.exe) that usually runs when a user logs on.
You can also configure Shell Launcher to launch different shell applications for different users or user groups.
There are a few exceptions to the applications and executables you can use as a custom shell:
- You can't use the following executable as a custom shell: `C:\\Windows\\System32\\Eshell.exe`. Using Eshell.exe as the default shell will result in a blank screen after user signs in.
- You can't use a Universal Windows app as a custom shell.
- You can't use a custom shell to launch Universal Windows apps, for example, the Settings app.
- You can't use an application that launches a different process and exits as a custom shell. For example, you can't specify **write.exe** in Shell Launcher. Shell Launcher launches a custom shell and monitors the process to identify when the custom shell exits. **Write.exe** creates a 32-bit wordpad.exe process and exits. Because Shell Launcher isn't aware of the newly created wordpad.exe process, Shell Launcher takes action based on the exit code of **Write.exe**, and restart the custom shell.
- You can't prevent the system from shutting down. For Shell Launcher V1 and V2, you can't block the session ending by returning FALSE upon receiving the [WM_QUERYENDSESSION](/windows/win32/shutdown/wm-queryendsession) message in a graphical application or returning FALSE in the [handler routine](/windows/console/handlerroutine) that is added through the [SetConsoleCtrlHandler](/windows/console/setconsolectrlhandler) function in a console application.
> [!NOTE]
> You cannot configure both Shell Launcher and assigned access on the same system.
>
> Use **Shell Launcher V2**, you can specify a Universal Windows app as a custom shell. Check [Use Shell Launcher to create a Windows 10 kiosk](/windows/configuration/kiosk-shelllauncher) for the differences between Shell Launcher v1 and Shell Launcher V2.
Shell Launcher processes the **Run** and **RunOnce** registry keys before starting the custom shell, so your custom shell doesn't need to handle the automatic startup of other applications and services.
Shell Launcher also handles the behavior of the system when your custom shell exits. You can configure the shell exit behavior if the default behavior doesn't meet your needs.
Methods of controlling access to other desktop applications and system components can be used in addition to using the Shell Launcher such as, [Group Policy](https://www.microsoft.com/download/details.aspx?id=25250), [AppLocker](/windows/iot/iot-enterprise/customize/application-control#applocker), and [Mobile Device Management](/windows/client-management/mdm/)
> [!NOTE]
>
> In Shell Launcher v1, available in Windows 10, you can only specify a Windows desktop application as the replacement shell. In Shell Launcher v2, available in Windows 10, version 1809 and above, you can also specify a UWP app as the replacement shell.
>
> To use Shell Launcher v2 in version 1809, you need to install the [KB4551853 update](https://support.microsoft.com/topic/may-12-2020-kb4551853-os-build-17763-1217-c2ea33f7-4506-dd13-2739-d9c7bb80b26d).
## Differences between Shell Launcher v1 and Shell Launcher v2
Shell Launcher v1 replaces ```explorer.exe```, the default shell, with ```eshell.exe```, which can launch a Windows desktop application.
Shell Launcher v2 replaces ```explorer.exe``` with ```customshellhost.exe```. This new executable file can launch a Windows desktop application or a UWP app.
In addition to allowing you to use a UWP app for your replacement shell, Shell Launcher v2 offers more enhancements:
- You can use a custom Windows desktop application that can then launch UWP apps, such as Settings and Touch Keyboard.
- From a custom UWP shell, you can launch secondary views and run on multiple monitors.
- The custom shell app runs in full screen, and can run other apps in full screen on user's demand.
For sample XML configurations for the different app combinations, see [Samples for Shell Launcher v2](https://github.com/microsoft/Windows-IoT-Samples/tree/master/samples/ShellLauncher/ShellLauncherV2).
## Requirements
Windows 10 Enterprise or Windows 10 Education.
## Terminology
- **Turn on, enable:** To make the setting available to the device and optionally apply the settings to the device.
- **Configure:** To customize the setting or subsettings.
- **Embedded Shell Launcher:** This feature is called Embedded Shell Launcher in Windows 10, version 1511.
- **Custom Shell Launcher:** This feature is called Shell Launcher in Windows 10, version 1607 and later.
## Turn on Shell Launcher
Shell Launcher is an optional component and isn't turned on by default in Windows 10. It must be turned on prior to configuring. You can turn on and configure Shell Launcher in a customized Windows 10 image (.wim) if Microsoft Windows hasn't been installed. If Windows has already been installed, you must turn on Shell Launcher before applying a provisioning package to configure Shell Launcher.
### Enable Shell Launcher using Control Panel
1. In the **Search the web and Windows** field, type **Programs and Features** and either press **Enter** or tap or select **Programs and Features** to open it.
1. In the **Programs and Features** window, select **Turn Windows features on or off**.
1. In the **Windows Features** window, expand the **Device Lockdown** node, select or clear the checkbox for **Shell Launcher**, and then select **OK.**
1. The **Windows Features** window indicates that Windows is searching for required files and displays a progress bar. Once found, the window indicates that Windows is applying the changes. When completed, the window indicates the requested changes are completed.
1. Select **Close** to close the **Windows Features** window.
> [!NOTE]
> Turning on Shell Launcher does not require a device restart.
### Enable Shell Launcher by calling WESL_UserSetting
1. Enable or disable Shell Launcher by calling the WESL_UserSetting.SetEnabled function in the Windows Management Instrumentation (WMI) class WESL_UserSetting.
1. If you enable or disable Shell Launcher using WESL_UserSetting, the changes don't affect any sessions that are currently signed in; you must sign out and sign back in.
This example uses a Windows image called install.wim, but you can use the same procedure to apply a provisioning package (for more information on DISM, see [What Is Deployment Image Servicing and Management](/windows-hardware/manufacture/desktop/what-is-dism).
### Enable Shell Launcher using DISM
1. Open a command prompt with administrator privileges.
1. Copy install.wim to a temporary folder on hard drive (in the following steps, we assume it's called C:\\wim).
1. Create a new directory.
```CMD
md c:\wim
```
1. Mount the image.
```CMD
dism /mount-wim /wimfile:c:\bootmedia\sources\install.wim /index:1 /MountDir:c:\wim
```
1. Enable the feature.
```CMD
dism /image:c:\wim /enable-feature /all /featureName:Client-EmbeddedShellLauncher
```
1. Commit the change.
```CMD
dism /unmount-wim /MountDir:c:\wim /Commit
```
### Enable Shell Launcher using Windows Configuration Designer
The Shell Launcher settings are also available as Windows provisioning settings so you can configure these settings to be applied during the image runtime. You can set one or all Shell Launcher settings by creating a provisioning package using Windows Configuration Designer and then applying the provisioning package during image deployment time or runtime. If Windows hasn't been installed and you're using Windows Configuration Designer to create installation media with settings for Shell Launcher included in the image or you're applying a provisioning package during setup, you must enable Shell Launcher on the installation media with DISM in order for a provisioning package to successfully apply.
Use the following steps to create a provisioning package that contains the ShellLauncher settings.
1. Build a provisioning package in Windows Configuration Designer by following the instructions in [Create a provisioning package for Windows 10](/windows/configuration/provisioning-packages/provisioning-create-package).
1. In the **Available customizations** page, select **Runtime settings** > **SMISettings** > **ShellLauncher**.
1. Set the value of **Enable** to **ENABLE**. More options to configure Shell Launcher appears, and you can set the values as desired.
1. Once you have finished configuring the settings and creating the provisioning package, you can apply the package to the image deployment time or runtime. See the [Apply a provisioning package](/windows/configuration/provisioning-packages/provisioning-apply-package) for more information. The process for applying the package to a Windows 10 Enterprise image is the same.
## Configure Shell Launcher
There are two ways you can configure Shell Launcher:
1. In Windows 10, version 1803, you can configure Shell Launcher using the **ShellLauncher** node of the Assigned Access Configuration Service Provider (CSP). See [AssignedAccess CSP](/windows/client-management/mdm/assignedaccess-csp) for details. Configuring Shell Launcher using this method also automatically enables Shell Launcher on the device, if the device supports it.
1. Use the Shell Launcher WMI providers directly in a PowerShell script or application.
You can configure the following options for Shell Launcher:
- Enable or disable Shell Launcher.
- Specify a shell configuration for a specific user or group.
- Remove a shell configuration for a specific user or group.
- Change the default shell configuration.
- Get information on a shell configuration for a specific user or group.
Any changes don't take effect until a user signs in.
## Launch different shells for different user accounts
By default, Shell Launcher runs the default shell, which is specified when you create the OS image at design time. The default shell is set to Cmd.exe, but you can specify any executable file to be the default shell.
You can configure Shell Launcher to launch a different shell for specific users or groups if you don't want to run the default shell. For example, you might configure a device to run a custom application shell for guest accounts, but run the standard Windows Explorer shell for administrator accounts in order to service the device.
If you use the WMI providers to configure Shell Launcher for a user or group at run time, you must use the security identifier (SID) for that user or group; you can't use the user name or group name.
For more information about common security identifiers, see [Well-known SIDs](/windows/win32/secauthz/well-known-sids).
When the current signed in account belongs to two or more groups that have different configurations defined for each group, Shell Launcher uses the first configuration it finds. The search order isn't defined, so we recommend that you avoid assigning a user to multiple groups with different Shell Launcher configurations.
## Perform an action when the shell exits
When a custom shell exits, Shell Launcher can perform one of four actions:
|Action|Description|
|:---:|:---|
|0|Restart the shell.|
|1|Restart the device.|
|2|Shut down the device.|
|3|Do nothing.|
> [!IMPORTANT]
> Make sure that your shell application does not automatically exit and is not automatically closed by any features such as Dialog Filter, as this can lead to an infinite cycle of exiting and restarting, unless the return code action is set to do nothing.
### Default return code action
You can define a default return code action for Shell Launcher with the DefaultReturnCodeAction setting. If you don't change the initial value, the default return code action is set to 0 (zero), which indicates that Shell Launcher restarts the shell when the shell exits.
### Map the exit code to a Shell Launcher action
Shell Launcher can take a specific action based on the exit code returned by the shell. For any given exit code returned by the shell, you can configure the action that Shell Launcher takes by mapping that exit code to one of the shell exit actions.
If the exit code doesn't match a defined value, Shell Launcher performs the default return code action.
For example, your shell might return exit code values of -1, 0, 1, or 255 depending on how the shell exits. You can configure Shell Launcher to:
- restart the device (1) when the shell returns an exit code of value -1
- restart the shell (0) when the shell returns an exit code of value 0
- do nothing (3) when the shell returns an exit code of value 1
- shut down the device (2) when the shell returns an exit code of value 255
Your custom return code action mapping would look like this:
|Exit code|Action|
|:----:|----|
|-1|1 (restart the device)|
|0|0 (restart the shell)|
|1|3 (do nothing)|
|255|2 (shut down the device)|
## Set your custom shell
Modify the following PowerShell script as appropriate and run the script on the device.
```PowerShell
# Check if shell launcher license is enabled
function Check-ShellLauncherLicenseEnabled
{
[string]$source = @"
using System;
using System.Runtime.InteropServices;
static class CheckShellLauncherLicense
{
const int S_OK = 0;
public static bool IsShellLauncherLicenseEnabled()
{
int enabled = 0;
if (NativeMethods.SLGetWindowsInformationDWORD("EmbeddedFeature-ShellLauncher-Enabled", out enabled) != S_OK) {
enabled = 0;
}
return (enabled != 0);
}
static class NativeMethods
{
[DllImport("Slc.dll")]
internal static extern int SLGetWindowsInformationDWORD([MarshalAs(UnmanagedType.LPWStr)]string valueName, out int value);
}
}
"@
$type = Add-Type -TypeDefinition $source -PassThru
return $type[0]::IsShellLauncherLicenseEnabled()
}
[bool]$result = $false
$result = Check-ShellLauncherLicenseEnabled
"`nShell Launcher license enabled is set to " + $result
if (-not($result))
{
"`nThis device doesn&#39;t have required license to use Shell Launcher"
exit
}
$COMPUTER = "localhost"
$NAMESPACE = "root\standardcimv2\embedded"
# Create a handle to the class instance so we can call the static methods.
try {
$ShellLauncherClass = [wmiclass]"\\$COMPUTER\${NAMESPACE}:WESL_UserSetting"
} catch [Exception] {
write-host $_.Exception.Message;
write-host "Make sure Shell Launcher feature is enabled"
exit
}
# This well-known security identifier (SID) corresponds to the BUILTIN\Administrators group.
$Admins_SID = "S-1-5-32-544"
# Create a function to retrieve the SID for a user account on a machine.
function Get-UsernameSID($AccountName) {
$NTUserObject = New-Object System.Security.Principal.NTAccount($AccountName)
$NTUserSID = $NTUserObject.Translate([System.Security.Principal.SecurityIdentifier])
return $NTUserSID.Value
}
# Get the SID for a user account named "Cashier". Rename "Cashier" to an existing account on your system to test this script.
$Cashier_SID = Get-UsernameSID("Cashier")
# Define actions to take when the shell program exits.
$restart_shell = 0
$restart_device = 1
$shutdown_device = 2
$do_nothing = 3
# Examples. You can change these examples to use the program that you want to use as the shell.
# This example sets the command prompt as the default shell, and restarts the device if the command prompt is closed.
$ShellLauncherClass.SetDefaultShell("cmd.exe", $restart_device)
# Display the default shell to verify that it was added correctly.
$DefaultShellObject = $ShellLauncherClass.GetDefaultShell()
"`nDefault Shell is set to " + $DefaultShellObject.Shell + " and the default action is set to " + $DefaultShellObject.defaultaction
# Set Internet Explorer as the shell for "Cashier", and restart the machine if Internet Explorer is closed.
$ShellLauncherClass.SetCustomShell($Cashier_SID, "c:\program files\internet explorer\iexplore.exe www.microsoft.com", ($null), ($null), $restart_shell)
# Set Explorer as the shell for administrators.
$ShellLauncherClass.SetCustomShell($Admins_SID, "explorer.exe")
# View all the custom shells defined.
"`nCurrent settings for custom shells:"
Get-WmiObject -namespace $NAMESPACE -computer $COMPUTER -class WESL_UserSetting | Select Sid, Shell, DefaultAction
# Enable Shell Launcher
$ShellLauncherClass.SetEnabled($TRUE)
$IsShellLauncherEnabled = $ShellLauncherClass.IsEnabled()
"`nEnabled is set to " + $IsShellLauncherEnabled.Enabled
# Remove the new custom shells.
$ShellLauncherClass.RemoveCustomShell($Admins_SID)
$ShellLauncherClass.RemoveCustomShell($Cashier_SID)
# Disable Shell Launcher
$ShellLauncherClass.SetEnabled($FALSE)
$IsShellLauncherEnabled = $ShellLauncherClass.IsEnabled()
"`nEnabled is set to " + $IsShellLauncherEnabled.Enabled
```
> [!NOTE]
> The previous script includes examples of multiple configuration options, including removing a custom shell and disabling Shell Launcher. It is not intended to be run as-is.
## Shell Launcher user rights
A custom shell is launched with the same level of user rights as the account that is signed in. This means that a user with administrator rights can perform any system action that requires administrator rights, including launching other applications with administrator rights, while a user without administrator rights can't.
> [!WARNING]
> If your shell application requires administrator rights and needs to be elevated, and User Account Control (UAC) is present on your device, you must disable UAC in order for Shell Launcher to launch the shell application.
## Related articles
- [Unbranded Boot](../unbranded-boot/index.md)
- [Custom Logon](../custom-logon/index.md)
- [Use Shell Launcher to create a Windows 10 Kiosk](/windows/configuration/kiosk-shelllauncher)
- [Launch different shells for different user accounts](/windows-hardware/customize/enterprise/shell-launcher#launch-different-shells-for-different-user-accounts)
- [Perform an action when the shell exits](/windows-hardware/customize/enterprise/shell-launcher#perform-an-action-when-the-shell-exits)
- [Shell Launcher user rights](/windows-hardware/customize/enterprise/shell-launcher#shell-launcher-user-rights)

0
windows/configuration/assigned-access/shell-launcher/quickstart-kiosk.md → windows/configuration/shell-launcher/quickstart-kiosk.md
View File

12
windows/configuration/shell-launcher/toc.yml
View File

@ -1,9 +1,12 @@
items:
- name: Shell Launcher
items:
- name: Overview
- name: What is Shell Launcher?
href: index.md
- name: "Quickstart: Configure a kiosk with Shell Launcher"
href: quickstart-kiosk.md
- name: Create a Shell Launcher configuration file
href: configuration-file.md
- name: Shell Launcher XSD
href: xsd.md
- name: WMI Provider Reference
items:
- name: Class WESL_UserSetting
@ -22,4 +25,3 @@ items:
href: wesl-usersettingsetdefaultshell.md
- name: SetEnabled
href: wesl-usersettingsetenabled.md

0
windows/configuration/assigned-access/shell-launcher/xsd.md → windows/configuration/shell-launcher/xsd.md
View File

4
windows/configuration/toc.yml
View File

@ -13,8 +13,8 @@ items:
href: store/toc.yml
- name: Cellular settings
href: cellular/provisioning-apn.md
- name: Kiosks and restricted user experiences
href: assigned-access/toc.yml
- name: Windows kiosk options
href: kiosk/toc.yml
- name: Multi-user and guest devices
href: shared-pc/toc.yml
- name: Provisioning packages