Windows - Enterprise Branding - Set Login Screen Background from Payload

remediation.ps1

<#
    .SYNOPSIS
        Configures login screen background for Windows 8+ devices.

    .PARAMETER imagePayload
        [ string ] : defines the name of the image file you attach to the Worklet's Payload.
            This should be the exact file name with extension upload to the Worklet's Payload.

        ** NOTE: ONLY PNG, JPG, JPEG, BMP, TIF AND GIF FILE EXTENSIONS ARE SUPPORTED. **
        ** NOTE: THIS VALUE IS CONFIGURED IN THE REMEDIATION SCRIPT **

    .PARAMETER AllowLockScreenImageChange
        [ boolean ] : defines whether users will be allowed to change the default logon screen background.

        OPTIONS:
            $true  - users will be allowed to change the logon screen background set by this policy
            $false - users will NOT be allowed to change the logon screen background set by this policy

    .PARAMETER CacheRoot
        [ string ] : the local directory that will be used to cache the logon background image.

        ** NOTE: This SHOULD NOT be changed unless absolutely necessary. All Automox 'Enterprise Branding' Worklets share this directory by default. **

    .NOTES
        - THIS WORKLET WILL NOT FUNCTION IF WINDOWS IS NOT ACTIVATED
        - A LOGOUT OR REBOOT OF THE DEVICE IS REQUIRED TO APPLY THESE CHANGES

    .HISTORY
        Author  : Anthony Maxwell
        Date    : 07/10/2023
        Version : 1.0.0
        - Initial Release.

        Author  : Anthony Maxwell
        Date    : 10/30/2023
        Version : 1.0.1
        - Replaced using assembly references with Add-Type in light of CSS template changes.

        Author  : Abhilasha M S
        Date    : 08/06/2024
        Version : 1.0.2
        - Made changes to change login screen background for Windows Professional devices

        Author  : John Guarracino
        Date    : 08/28/2024
        Version : 1.0.3
        - Updated to use an image attached to the Worklet Payload instead of a URL-sourced image.

#>

#########################################
# PARAMETERS

# define the path to download the background image
# This should be the exact file name of the payload you upload to the Worklet.
$imagePayload = 'myImage.jpg'

# allow users to change the logon screen background
# $true  - users will be allowed to change the logon screen background
# $false - users will NOT be allowed to change the logon screen background
$AllowLockScreenImageChange = $false

# define this worklet's cache directory
$CacheRoot = "$env:SYSTEMDRIVE\ProgramData\amagent\WorkletCache\Enterprise-Branding"

# define verbosity preference
# uncommenting this line will show add'l activity log output
# this is intended primarily for troubleshooting purposes
# $VerbosePreference = 'Continue'

Write-Verbose 'Parameter load complete.'

#########################################
# VARS

# define the image file name prefix
$imageName = 'AX-LockScreen'

# define the parent registry key path for Enterprise
$keyPathEnterprise = 'Software\Policies\Microsoft\Windows\Personalization'

# define the parent registry key path for Professional
$keyPathPro = 'SOFTWARE\Microsoft\Windows\CurrentVersion\PersonalizationCSP'

Write-Verbose 'Variable load complete.'

#########################################
# REMEDIATION

# --! Create Cache Directory !--

# evaluate image cache directory existence
if ( ![ System.IO.Directory ]::Exists( $CacheRoot ) )
{
    [ System.IO.Directory ]::CreateDirectory( $CacheRoot ) | Out-Null
    Write-Output "Creating cache directory `"$CacheRoot`"."
}

# --! Copy Image from Payload to Cache Directory !--
Write-Verbose "Copying $imagePayload to install directory."
[ System.IO.File ]::Copy( $imagePayload, "$CacheRoot\$imagePayload", $true )

# define the full file path
$imagePath = "$CacheRoot\$imagePayload"

# Checking for successful copy from Payload
If ( -Not [ System.IO.File ]::Exists( "$imagePath" ) ) {
    Write-Error "Background image file not found in the specified directory. Exiting."
    exit 3
}

else {
    Write-Verbose "Background image file successfully saved as `"$imagePath`"."
}

# --! Create Registry Key !--

# define the appropriate registry view
$view = ( [ Microsoft.Win32.RegistryView ]::Registry32, [ Microsoft.Win32.RegistryView ]::Registry64 )[ [ System.Environment ]::Is64BitOperatingSystem ]

# open the registry key for Enterprise
$keyEnterprise = [ Microsoft.Win32.RegistryKey ]::OpenBaseKey( [ Microsoft.Win32.RegistryHive ]::LocalMachine, $view )

# open the registry key for Professional
$keyPro = [ Microsoft.Win32.RegistryKey ]::OpenBaseKey( [ Microsoft.Win32.RegistryHive ]::LocalMachine, $view )

# evaluate registry key existence for Enterprise
if ( $null -eq $keyEnterprise.OpenSubKey( $keyPathEnterprise ) )
{
    Write-Verbose "Creating registry key `"$keyPathEnterprise`"."

    # create the subkey
    $keyEnterprise = $keyEnterprise.CreateSubKey( $keyPathEnterprise, $true )
}

else
{
    # retrieve the subkey
    $keyEnterprise = $keyEnterprise.OpenSubKey( $keyPathEnterprise, $true )
}

# evaluate registry key existence for Professional
if ( $null -eq $keyPro.OpenSubKey( $keyPathPro ) )
{
    Write-Verbose "Creating registry key `"$keyPathPro`"."

    # create the subkey
    $keyPro = $keyPro.CreateSubKey( $keyPathPro, $true )
}

else
{
    # retrieve the subkey
    $keyPro = $keyPro.OpenSubKey( $keyPathPro, $true )
}

Write-Verbose 'Registry key evaluation complete, proceeding to property remediation.'

# --! Set Registry Properties !--

try
{
    # set the LockScreenImage property for Enterprise
    $keyEnterprise.SetValue( 'LockScreenImage', $imagePath ) | Out-Null

    Write-Verbose "Created `"LockScreenImage`" property for Enterprise."

    # set the NoChangingLockScreen property for Enterprise
    $keyEnterprise.SetValue( 'NoChangingLockScreen', [ int ] !$AllowLockScreenImageChange, [ Microsoft.Win32.RegistryValueKind ]::DWord ) | Out-Null

    Write-Verbose "Created `"NoChangingLockScreen`" property for Enterprise."

    # set the LockScreenImagePath property for Professional
    $keyPro.SetValue( 'LockScreenImagePath', $imagePath ) | Out-Null

    Write-Verbose "Created `"LockScreenImagePath`" property for Professional."

}

catch
{
    Write-Error 'Failed to set registry property, exiting.'
    Write-Error '============ BEGIN ERROR LOG ============'
    Write-Error ( $Error -join "`n" )
    Write-Error '============  END ERROR LOG  ============'
    exit 1
}

Write-Output 'Remediation complete, exiting.'

exit 0