From aa2f45836dd7366f953690428b35338a63fc0229 Mon Sep 17 00:00:00 2001 From: Paolo Matarazzo <74918781+paolomatarazzo@users.noreply.github.com> Date: Fri, 28 Feb 2025 08:27:51 -0500 Subject: [PATCH] merge --- .../configure-multi-app-kiosk.md | 6 +- .../configuration/shell-launcher/configure.md | 213 +++++++++++++++++- .../configuration/shell-launcher/enable.md | 77 +++++++ windows/configuration/shell-launcher/index.md | 20 +- windows/configuration/shell-launcher/toc.yml | 4 +- 5 files changed, 305 insertions(+), 15 deletions(-) create mode 100644 windows/configuration/shell-launcher/enable.md diff --git a/windows/configuration/assigned-access/configure-multi-app-kiosk.md b/windows/configuration/assigned-access/configure-multi-app-kiosk.md index e1bff84d96..009311c3ef 100644 --- a/windows/configuration/assigned-access/configure-multi-app-kiosk.md +++ b/windows/configuration/assigned-access/configure-multi-app-kiosk.md @@ -7,7 +7,7 @@ ms.topic: overview # Configure a restricted user experience (multi-app kiosk) with Assigned Access -An Assigned Access restriced user experience runs one or more apps from the desktop. People using the kiosk have a customized Start menu that shows only the tiles for the apps that are allowed. With this approach, you can configure a locked-down experience for different account types. A multi-app kiosk is appropriate for devices that are shared by multiple people. +An Assigned Access restricted user experience runs one or more apps from the desktop. People using the kiosk have a customized Start menu that shows only the tiles for the apps that are allowed. With this approach, you can configure a locked-down experience for different account types. A multi-app kiosk is appropriate for shared devices. 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: @@ -102,11 +102,11 @@ The Assigned Access configuration takes effect the next time the targeted user s 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. +> 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 isn't triggered on VMs. ### Sign out of assigned access -By default, to exit the kiosk experience, press Ctrl + Alt + Del. 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: +By default, to exit the kiosk experience, press Ctrl + Alt + Del. The kiosk app exits automatically. If you sign in again as the Assigned Access account, or wait for the sign in screen time-out, the kiosk app relaunches. The default time-out is 30 seconds, but you can change the time-out with the registry key: `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\LogonUI` diff --git a/windows/configuration/shell-launcher/configure.md b/windows/configuration/shell-launcher/configure.md index a8e59f1b60..c9da0b19ea 100644 --- a/windows/configuration/shell-launcher/configure.md +++ b/windows/configuration/shell-launcher/configure.md @@ -1,18 +1,90 @@ --- -title: Configure a kiosk with Shell Launcher +title: Configure a Kiosk With Shell Launcher description: Learn how to configure a Windows kiosk with Shell Launcher. ms.date: 02/27/2025 -ms.topic: overview +ms.topic: How-to --- # Configure a kiosk with Shell Launcher +There are two ways you can configure Shell Launcher: + +1. Using the `ShellLauncher` node of the [Assigned Access Configuration Service Provider (CSP)](/windows/client-management/mdm/assignedaccess-csp), which also automatically enables Shell Launcher on the device, if the device supports it +1. Using the **Shell Launcher WMI providers** directly in an application. When using this method, you must [enable Shell Launcher](enable.md) first + +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 with the Assigned Access CSP + 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 +> [!NOTE] +> Configuring Shell Launcher using Assigned Access CSP, automatically enables Shell Launcher on the device, if the device supports it. + 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)] @@ -83,6 +155,143 @@ Write-Output "Successfully applied Shell Launcher configuration" > [!TIP] > For practical examples, see the [Quickstart: configure a kiosk experience with Shell Launcher](quickstart-kiosk.md). +## Set your custom shell with the WMI providers + +> [!NOTE] +> When using the WMI providers option, you must first [enable Shell Launcher](enable.md). + +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'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. + ## User experience After the settings are applied, the users that are configured to use Shell Launcher will execute the custom shell after sign-in. diff --git a/windows/configuration/shell-launcher/enable.md b/windows/configuration/shell-launcher/enable.md new file mode 100644 index 0000000000..a869e0e4d2 --- /dev/null +++ b/windows/configuration/shell-launcher/enable.md @@ -0,0 +1,77 @@ +--- +title: Enable Shell Launcher +description: Learn how to enable the Shell Launcher feature. +ms.date: 02/27/2025 +ms.topic: How-to +--- + +# Enable Shell Launcher + +> [!NOTE] +> Configuring Shell Launcher using Assigned Access CSP, automatically enables Shell Launcher on the device, if the device supports it. There's no need to enable Shell Launcher separately if you configure it using Assigned Access CSP. + +Shell Launcher is an optional component and isn't turned on by default in Windows. 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](/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 + +## Next steps + +> [!div class="nextstepaction"] +> Learn how to configure Shell Launcher: +> +> [Configure a kiosk with Shell Launcher](configure.md) diff --git a/windows/configuration/shell-launcher/index.md b/windows/configuration/shell-launcher/index.md index 2f8d7a22f4..38e386ccd6 100644 --- a/windows/configuration/shell-launcher/index.md +++ b/windows/configuration/shell-launcher/index.md @@ -7,15 +7,9 @@ ms.topic: overview # Shell Launcher Overview -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. +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. This feature is useful for creating a custom user experience on devices that are used for a specific purpose, including kiosks, ATMs, and digital signage. -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. +Shell Launcher controls which application a user gets as the shell after sign-in. It doesn't prevent a 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. You can also configure Shell Launcher to launch different shell applications for different users or user groups. 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: @@ -23,10 +17,18 @@ With Shell Launcher, you can use features and methods to control access to other - Group policy (GPO) - [AppLocker](/windows/security/threat-protection/windows-defender-application-control/applocker/applocker-overview) -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). +> [!NOTE] +>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 Configuration Options Overview](../kiosk/index.md). [!INCLUDE [shell-launcher](../../../includes/licensing/shell-launcher.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 administrative rights can perform any system action that requires administrative rights, including launching other applications with administrative rights. + +> [!WARNING] +> If your shell application requires administrative rights and needs to be elevated, and User Account Control (UAC) is enabled, you must disable UAC for Shell Launcher to launch the shell application. + ## Limitations Here are some limitations to consider when using Shell Launcher: diff --git a/windows/configuration/shell-launcher/toc.yml b/windows/configuration/shell-launcher/toc.yml index 70f1d9ea27..06459f5360 100644 --- a/windows/configuration/shell-launcher/toc.yml +++ b/windows/configuration/shell-launcher/toc.yml @@ -1,7 +1,7 @@ items: - name: Overview href: index.md -- name: 🟡 Overview (merge in progress ↖️) +- name: 🔴 Overview (merged to configure.md and enable.md ↙️) href: index_old.md - name: Configure a kiosk href: configure.md @@ -13,6 +13,8 @@ items: items: - name: Shell Launcher XSD href: xsd.md + - name: Enable Shell Launcher + href: enable.md - name: WMI Provider items: - name: Class WESL_UserSetting