1 of 100

Sitecore PowerShell Extensions

Introduction

About the Module

The (SPE) module is a Sitecore development accelerator that can drastically increase your productivity and curtail the amount of time it takes to deliver a Sitecore solution.

The module provides a command line (CLI) and a scripting environment (ISE) for automating tasks. SPE works with the Sitecore process, capable of making native calls to the Sitecore API and manipulating files. Running commands and writing scripts follow the standard and well-known Windows PowerShell syntax. Windows PowerShell is a common tool used in IT for desktop and server management, so we decided to stick with that as a framework to build upon.

Disclaimer

Since every environment is different, all code should not be run in a production environment without your team or organization thoroughly testing first. We recommend the use of a test lab environment often referred to as a development/staging instance of Sitecore.

The disclaimer is provided because someone somewhere will inevitably not follow this recommendation and if they do hose their Sitecore environment, they have no one to blame but themselves.

All data and information provided in this book are for informational purposes only. Adam Najmanowicz, Michael West, and the SPE Team make no representations as to accuracy, completeness, currentness, suitability, or validity of any information in this book and will not be liable for any errors, omissions, or delays in this information or any losses, injuries, or damages arising from its display or use. All information found in this book is provided "as is" with no express or implied warranties.

Installation

Review prerequisites and details on how to get setup with SPE.

Prerequisites

Take a quick look at the appendix to see which version of SPE you should be installing that is compatible with your Sitecore environment. Generally SPE has pretty good backwards compatibility but may require a new version to support the latest Sitecore CMS release.

Windows Management Framework 5.1 (PowerShell) is generally available for most Windows environments.
PowerShell set to RemoteSigned (probably optional)

The release of SPE 6.0 introduced name changes to some files which are now reflected throughout the documentation. Review to see the full scope of what changed. Any place where the name Cognifide or Cognifide.PowerShell was used is now replaced with Spe.

Docker

Working with Docker is going to be the preferred method of installation.

You can find two flavors of the images:

- Ex: docker pull sitecorepowershell/sitecore-powershell-extensions:6.4-1809
Sitecore Built

With this approach, you essentially add a new layer during your image build to include the files from the asset image. Here are some samples of what you can add to your existing setup. Check out Sitecore's samples for additional guidance.

docker-compose.yml

Dockerfile (mssql-init)

Dockerfile (cm)

Installation Wizard

The SPE module installs like any other for Sitecore. This approach is appropriate for installations not within a containerized environment.

the module from the GitHub releases page and install through the Installation Wizard.

For Sitecore 10.1 and newer along with Identity Server you should enable the provided configuration Spe.IdentityServer.config.
For Sitecore 10.1 and newer you can leverage the IAR packages. There is still the need for dacpac deployments because SPE includes a security user and role.
- An additional patch is required for 10.1 to include the location

Upgrade

We've tried to make upgrading SPE as seamless as possible. The following should provide you with some basic information on what to expect when upgrading.

From 6.x

You should be able to install directly over the previous installation of 6.0+.

For Sitecore 10.1 and newer along with Identity Server you should enable the provided configuration Spe.IdentityServer.config.
For Sitecore 10.1 and newer you can leverage the IAR packages. There is still the need for dacpac deployments because SPE includes a security user and role.
- An additional patch is required for 10.1 to include the location

Using packages with the Items as Resources (IAR) files will require additional steps to remove database records that correlate with the contents of the *.dat files. Refer to the Sitecore documentation when upgrading for the process to cleanup the databases. may be helpful if you wish to take a more precise approach.

From 5.x and older

These versions used a different name for the assemblies and configs. You may find it easier to delete all files originally distributed with SPE before installing a newer version. Here are a few steps to consider:

Delete all files in the bin and App_Config/Include directories prefixed with Cognifide.
Delete /sitecore modules/Shell/PowerShell
Delete /sitecore modules/PowerShell

Reference the original SPE package (if available) to identify if any other files were included.

Sitecore items in the content tree will potentially shuffle around into their new location. Be sure to backup your custom scripts first.

Troubleshooting

See the troubleshooting section

Contributor Guide

Support for Sitecore 7 has discontinued with SPE 5.0.

The following guide should provide you with enough information to setup a development environment configured to contribute to SPE. We'll begin with a single installation of Sitecore 8+.

The solution requires Visual Studio 2015 or later.

This guide assumes a source root location of "C:\Source" and a site root location of "C:\inetput\wwwroot". These are not prerequisites of the project, and you can use whatever folder locations suit you.

Single Instance for Sitecore 8 & 9

Meet the prerequisites found
Install Sitecore 8+ to a folder of your choice, for example C:\inetpub\wwwroot\SitecoreSPE_8
Clone the repo to your local development environment

Any changes you make going foward just require a build of the solution. Remember that when pulling down updates to the source, you should execute a Unicorn sync to ensure your items are up to date.

Multiple Instances

The SPE deployment process supports multiple sites and multiple versions of Sitecore. The following steps carry on from above to add further support for another Sitecore site, such as 8.x or 9.x.

Complete the steps for a Single Instance.
Install Sitecore 8.x/9.x to a folder of your choice, for example C:\inetpub\wwwroot\SitecoreSPE_91
Edit the sites definition in deploy.user.json to add your new Sitecore web root folder. Set the

SPE can be deployed to as many Sitecore sites as you like. Each time you first deploy to a new installation, make sure you use Unicorn to sync the latest state of items into Sitecore.

Optional: PowerShell Remoting support

To add the SPE PowerShell Remoting Module scripts into your machine's PowerShell Module path, execute the .\Setup_Module.ps1 script from the source folder. This will add the \Modules folder from source into your PSModulePath environment variable. Once this is done, you can use Import-Module SPE on your development machine to run the remoting scripts.

Optional: Junction Support

As part of the SPE deployment process, all of the relevant binary, configuration and sitecore module files are copied over from the projects within the solution. This means that any changes to static files such as JS / CSS files require a full build for these to be deployed to the site. As the build triggers an application pool recycle of your site, this can be a little slow for quick changes.

For more rapid development, you can enable junction deployment on your sites. When this is enabled, rather than copying over the static files, will be setup for various folders so that the folders within the Sitecore installation are directly linked to the source folder. Any changes made in the solution are seen instantly, because the solution and the site are referencing the exact same files.

To enable a junction deployment for a site, add junction property to the site definition and set it to true:

Note that with junction deployments, a solution build is still required if you want to deploy any code or .config changes.
It is not currently supported for a junction deployment site to be changed back into a non-junction deployment site. If you wish to do this, you should manually delete the following folders from your Sitecore installation before updating the junction property back to false: sitecore modules\PowerShell and sitecore modules\Shell\PowerShell

Interfaces

SPE includes several built-in interfaces for managing and executing scripts, as well as provides tools for modifying content.

Here we'll discuss the Console, ISE, and other dialogs made available through SPE.

Console

The Console is a command line interface (CLI) designed for efficiency, providing a streamlined tool for working with Windows PowerShell and Sitecore.

The default security configuration for SPE requires the Console to be in an before allowing the execution of commands. The following figure shows the Console when the User Account Controls (UAC) are disabled. While this is a common configuration for developers, we highly encourage you to ensure UAC is enabled in higher environments.

Shortcuts

Interface Configuration

Colors

The Console, ISE, and Result dialog all provide a way a way to view output data. The $host variable provides access to configuring the colors for this output data.

Example: The following configures colors for the background and forground text in multiple streams.

Help

There are multiple methods of accessing help documentation in SPE to provide you with information on the commands available to you.

Viewing all available commands

A report is available which will show you all available SPE commands:

When executed, this report provides a paged view of the SPE commands.

Viewing command help

Console

To display the available help for a command in the Console, simply use the Get-Help command:

For full documentation, including examples, use the -Full parameter:

ISE

Through the Integrated Scripting Environment (ISE), SPE provides a method of acccessing help for available commands. To view the help for a command, simply highlight the command and press Ctrl + Enter.

After doing this, a dialog will appear with the relevant help information:

Documenting functions

When writing scripts, you are able to include formatted comments that will be used to provide help text for functions. If formatted correctly, this help text will be available through the methods described above.

Example: A simple function with documentation:

Once the script containing this function has been invoked, the help text will be available:

For further information on comment-based help, refer to the .

Online appendix

Online help is additionaly available for all SPE commands in this documentation, with detailed explanations of commands and their parameters, along with useful examples. These can be found in the .

Variables

There are several variables available out of the box for use in running commands and scripts. Many of the variables prefixed with Sitecore derive from the Sitecore.config settings. Run the command Get-Variable to see the complete list available in the currently running session.

Variable

Example

AppPath

C:\Inetpub\wwwroot\Console\Website\

Note: Any new variables created are stored within the current session; when the session ends the variables are removed. Be careful not to overwrite the built-in variables.

Item Languages

The section on working with items provided a variety of examples in retrieving items based on their language. In this section will show how to manage items and their languages.

Add Language Version

Example: The following example queries all of the content items and adds a new language version of "en-ca", while overwriting any that exist.

Example: The following example adds a language version from English to US and Polish while leaving the Title field blank. If a version already exists nothing happens.

Example: The following example adds a language version from English to Polish of Template Name Sample Item. If the version exists a new version is created for that language. Finally the results are displayed as a table showing only the Name, Language, and Version.

Example: The following example adds a language version in Polish to the Home item and all its children. If the version exists nothing happens. No fields were harmed in the making of this version.

Remove Language Version

Example: The following example queries all of the content items and removes the language version of "fr-CA".

New Item with Forced Language Version

Example: The following example creates a new item with language versions only matching the specified languages; all other language version are removed.

Parameters and Configuration

Supported parameters:

-Recurse Translates item and its children
-IfExist Accepts one of 3 pretty self explanatory actions: Skip, Append or OverwriteLatest

On top of the ignored fields in the -IgnoredFields the following fields are ignored as configured within the Spe.config file:

References

Control Panel

Administration

Note: Examples included in the following modules

System Maintenance

Analytics

Database

Globalization

Preferences

Reports

Note: Examples included in the following modules

System Maintenance

Security

Data Sources

Scripted Data Sources provide a way to use a PowerShell script to perform complex queries.

Here are some good reasons to use this feature:

Delivering complex functionality based on multiple criteria.
Your field may need to provide different set of items to choose from based on:
- user name or role (in simplest case this can be done using right management, but maybe not always possible in a more elaborate scenario)
- current day or month?
- In a multisite/multimarket scenario you may want to show different items for each site
  based on engagement analytics parameters of the page

Something that would be beyond the reach of a regular Sitecore query and potentially something that you would really need to deliver code source for. But maybe you’re not in a position to deploy that on your environment?

Field Data Source

Field Data Source provides a great opportunity for a script.

Below are field types you may wish to use a script:

Checklist
Droplist
Grouped Droplink

Rendering Data Source Roots

//TODO

Rendering Data Source Items

//TODO

References

PowerShell Scripted Data Sources and
Sitecore Spark on using scripted datasources

Event Handlers

The Event Handler integration provides a way to execute scripts when defined events are fired.

Steps required to activate this integration include the following:

Enable the Spe.Events.config or apply your own patch with the required events enabled.
Add a new integration point library to your new or existing module.

Functions

The Functions integration allows for scripts to be discoverable through autocomplete while authoring scripts. Functions can be "disabled" by disabling the containing module.

Begin by adding a script library called "Functions" to a module. This can be created by the new module wizard.
Add a script to the "Functions" script library with a name that represents the purpose.
Use the command Import-Function to discover the available functions.

Note: It's best practice to create function scripts that follow the Verb-Noun pattern as outlined by Microsoft.

Here's a short video on authoring custom functions.

ISE Plugins

Custom ribbon commands for use in the ISE.

You can include custom ribbon commands in the ISE to aid in improving the script authoring experience.

Add a custom plugin

For this example, we wish to have a plugin that analyzes the script and reports on any errors.

Create a new script stored under the following structure:

The path structure needs to follow [MODULE]/Internal/ISE Plugins/[PLUGIN_NAME]. Here we have X-Demo/Internal/ISE Plugins/Analyze Script.

Use the following sample to fill in the script body.

Now you can run the command from the ribbon and see the results in the ISE.

Pipelines

Use the following in your scripts to get access to the arguments passed to the processor.

Configure any Enable rules to ensure your script only runs when necessary.

Logging In

Note: Examples included in the following modules

Tasks

The task scheduler is a great way to run scripts in a periodic fashion. You may find the need to automatically archive log files into a compressed file. Perhaps send an email with a generated report based on stale site content.

Video Tutorial

Click for a demo

Scheduled Task Command

To help make the setup simple, we've provided a Task Command.

The command shown above is simply a type exposed as a public method in the Spe assembly. There exists an update method which accepts one or more items and executes the associated script.

Beneath Schedules you can create as many tasks as Sitecore will allow. Configure the Command and Items fields like that shown below.

The Items field contains the path to a script in the Script Library.

Below are some of the scripts found out-of-the-box with SPE.

Module

Script

Create and Manage Tasks

We've added a context menu item to provide you with a shortcut to the Task Scheduler Editor.

Create a new scheduled task:

Run or edit the scheduled task:

The scheduled task is capable of running 1-to-many scripts. Choose all that apply for the selected task. Each script runs within a shared session, making it possible to share results between scripts.

Note: Make use of the Enable Rule to take advantage of the rules engine.

The task schedule has an intuitive dialog for working with and changing the frequency.

Note: Examples included are in the following modules

License Expiration
Media Library Maintenance
System Maintenance

See how Adam added .

Web API

The Web API integration point exposes scripts through a url. This can be especially helpful when a script needs to be executed on the server but without knowledge of the script contents.

The url will look something like the following:

Here's the url broken down:

API Version - Specifies which service is being requested.

Workflows

The Workflows integration allows for scripts to run like workflow commands. Rules can be used to control visiblity and enablement. The script is only executed when the command is triggered.

Begin by adding a new item to a workflow command of template type /Modules/PowerShell Console/PowerShell Script Workflow Action. We've added an insert option to help with this.
Edit the Type string field to your custom type or to the built in type

Packaging

Ever wanted to package up items and files without opening the Sitecore Package Designer each time? There are a number of commands available for generating packages.

Package Creation

Example: The following example demonstrates how to generate a package.

$package = New-Package "Package-of-Stuff"
$package.Sources.Clear()

$package.Metadata.Author = "Michael West"
$package.Metadata.Publisher = "Team Awesome"
$package.Metadata.Version = "1.0"
$package.Metadata.Readme = @"
Set of instructions for the user.
"@

# Items using New-ItemSource and New-ExplicitItemSource
$source = Get-Item -Path "master:\templates\Feature\Forms" | 
    New-ItemSource -Name 'Feature Forms Items' -InstallMode Overwrite
$package.Sources.Add($source)

# Files using New-FileSource and New-ExplicitFileSource
$source = Get-Item -Path "$AppPath\App_Config\Include\Feature\Forms\Company.Feature.Forms.config" | 
    New-ExplicitFileSource -Name "Feature Forms Files"
$package.Sources.Add($source)

Export-Package -Project $package -Path "$($package.Name)-$($package.Metadata.Version).xml"
Export-Package -Project $package -Path "$($package.Name)-$($package.Metadata.Version).zip" -Zip
Download-File "$SitecorePackageFolder\$($package.Name)-$($package.Metadata.Version).zip"

Post Step

Example: The following adds a Post Step and custom attributes.

Example: The following adds a Post Step included with SPE to delete a file. The SPE Post Step code reads xml data stored in the comment section of the package.

Example: The following adds a Post Step Script included with SPE to change icons. The SPE Post Step code executes a script included with the package as stored in the attributes section.

Users and Roles

Managing users and roles is a big topic and this section won't cover everything. We aim to show you different problems that have come up and how we solved them.

Example: The following command returns the security commands available.

Users

Managing users should be a pretty straight forward task. While the User Manager provided by Sitecore is handy, you'll likely find yourself wanting to make bulk changes. The following examples should give you a few ideas about how to manage user accounts.

Troubleshooting

General

We generally see issues occurring due to an incompatible version of Windows PowerShell. Be sure to install Windows PowerShell version 3 or newer.

Manage Templates

Examples for managing item templates.

Manage Templates

Change Template

# Sample Item
$sourceTemplate = Get-Item -Path "master:\{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
# Sample Content
$targetTemplate = Get-Item -Path "master:\{93A8866B-972F-4FBF-8FD9-D6004B18C0AF}"

# Use Get-ItemReferrer to find all items referencing the template, rather than scanning the content tree.
$sourceTemplate | Get-ItemReferrer | 
    Where-Object { $PSItem.TemplateId -eq $sourceTemplate.ID -and $PSItem.Paths.IsContentItem } |
    ForEach-Object {
        Set-ItemTemplate -Item $PSItem -TemplateItem $targetTemplate
    }

Sitecore Stack Exchange

The following examples are best kept on SSE since it provides more context about the problem being solved.

Find all items based on a template found anywhere in the inheritance chain.

Close-Window

Closes the runner job window after the script completes.

Syntax

Close-Window

Detailed Description

Ensures the runner process window is closed after the script finishes execution. This is commonly used when the runner should close after a report runs while in the Desktop mode.

Parameters

Notes

Help Author: Adam Najmanowicz, Michael West

Examples

EXAMPLE

ConvertTo-CliXml

Exports Microsoft .NET objects froms PowerShell to a CliXml string.

Syntax

ConvertTo-CliXml [-InputObject] <PSObject>

Detailed Description

The ConvertTo-CliXml command exports Microsoft .NET Framework objects from PowerShell to a CliXml string.

Parameters

-InputObject <PSObject>

Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-CliXml.

Aliases

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

object

Outputs

The output type is the type of the objects that the cmdlet emits.

System.String

Notes

Help Author: Adam Najmanowicz, Michael West

Examples

EXAMPLE

ConvertFrom-Xml

Get-Cache

Retrieves a Sitecore cache.

Syntax

Get-Cache [[-Name] <String>]

Get-UserAgent

Returns the current user's browser user agent.

Syntax

Detailed Description

Returns current user's browser user agent. Works only if Console is running outside of job. (e.g. in ISE - script needs to be run from the dropdown under the "Execute" button)

Parameters

Outputs

The output type is the type of the objects that the cmdlet emits.

System.String

Notes

Help Author: Adam Najmanowicz, Michael West

Examples

EXAMPLE

Invoke-JavaScript

Syntax

Detailed Description

Delegated Access

Delegated Access allows lower-privileged users to run specific scripts with elevated permissions by impersonating a power user. This provides controlled privilege escalation for trusted operations without granting users permanent elevated access.

Overview

Delegated Access solves a common problem: You want to give content authors access to specific administrative tasks without making them full administrators.

Without Delegated Access:

Grant users broad administrative roles
Risk: Users have more permissions than needed
Violates principle of least privilege

With Delegated Access:

Users keep limited permissions
Specific scripts run with elevated permissions
All actions are logged with both user identities

This feature was introduced in SPE with

Use Cases

Content Author Needs Publishing Rights

Scenario: Content authors need to publish items but shouldn't have global publish rights.

Solution: Create a script that publishes specific items, configured to run as an administrator via delegated access.

Reports Requiring Administrative Access

Scenario: Managers need to run reports that query all items, but they have limited content access.

Solution: Configure the report script to impersonate an administrator, allowing full content access for the report only.

Bulk Operations on Protected Content

Scenario: A user needs to perform bulk updates on items they normally can't modify.

Solution: Create a controlled script with delegated access that performs the specific operation.

Workflow Actions

Scenario: Users need to trigger workflow commands that require elevated permissions.

Solution: Workflow scripts run with delegated access to perform administrative actions.

How It Works

Components

Delegated Access Item - Configuration item that defines the delegation
Requester Role - Sitecore role containing lower-privileged users
Impersonated User - Power user account whose permissions are used

Execution Flow

Configuration Steps

Step 1: Create Delegated Access Item

Navigate in Content Editor to where delegated access configurations are stored and use the insert option.

Step 2: Configure Requester Role

Enter the role that contains the lower-privileged users who should have delegated access.

Field: Requester Role

Example Values:

sitecore\Elevated Unlock - Custom role for editors

Why use roles instead of users?

Easier to manage
Follows role-based access control (RBAC) best practices
Changes apply to all role members automatically

Step 3: Configure Impersonated User

Enter the user account whose permissions will be used when scripts execute.

Field: Impersonated User

Example Values:

sitecore\Admin - Full administrative access
sitecore\PowerUser - Custom account with specific elevated permissions

Security Consideration: The impersonated user should have the minimum permissions needed for the delegated scripts. Don't always use sitecore\Admin - create dedicated service accounts with specific permissions instead.

Step 4: Select Delegated Scripts

Choose which scripts and libraries should run with delegated access and ensure the appropriate rules are configured.

See the Security Management script module for more examples:

/sitecore/system/Modules/PowerShell/Script Library/SPE/Tools/Security Management

What to include:

Scripts that should run with elevated permissions
Script libraries containing those scripts
Scripts with rules that check for delegated access

Multilist Field: Select from available PowerShell scripts and script libraries.

Step 5: Enable the Configuration

Check the "Enabled" field to activate the delegated access configuration.

Field: Enabled (checkbox)

Important: Test thoroughly before enabling in production. Delegated access grants powerful permissions to lower-privileged users.

Audit Logging

All delegated access operations are logged to the SPE log file.

Log Entry Format:

Log Components:

Timestamp: When the script executed
Script ID: Unique identifier for the script
Context User: The actual logged-in user

Monitoring Delegated Access

Regular log review should include:

✅ Monitor for:

Unexpected impersonation attempts
Scripts running as admin that shouldn't
Failed delegated access attempts

Example log analysis query:

Best Practices

Security Recommendations

✅ Do:

Use dedicated service accounts instead of sitecore\Admin when possible
Limit delegated scripts to specific, necessary operations
Regularly audit who has delegated access (review role membership)

❌ Don't:

Grant delegated access to broad roles like "Everyone"
Always impersonate sitecore\Admin - use least privilege
Allow arbitrary code execution in delegated scripts

Configuration Guidelines

Aspect

Recommendation

Why

Script Security

When writing scripts for delegated access:

Validate All Input:
Limit Scope:
Confirm Destructive Operations:

Troubleshooting

Delegated access doesn't work

Possible causes:

Delegated access item is not enabled
User is not in the requester role
Script is not selected in the delegated scripts field
Script library containing the script is not selected or enabled.

Solution: Verify all configuration fields and ensure the user is in the correct role.

Script runs with current user permissions instead of impersonated

Cause: Script or script library not included in delegated scripts selection.

Solution: Add both the script AND its parent library to the delegated scripts field.

Can't see delegated access insert option

Cause: Insert options not configured or user lacks permissions.

Solution: Verify insert options are configured on the parent item and user has write access.

Impersonated user doesn't have expected permissions

Cause: Impersonated user account lacks necessary Sitecore permissions.

Solution: Grant the impersonated user account the required Sitecore roles and item permissions.

Security Considerations

Risks

Risk

Mitigation

Defense in Depth

Layer multiple security controls:

Role Membership - Only trusted users in requester role
Script Security - Item-level security on delegated scripts
Input Validation - Scripts validate and limit operations

- Understand SPE security model
- Additional authentication layer
- Managing Sitecore roles

References

- Feature introduction

Security

Sitecore PowerShell Extensions (SPE) is a powerful administrative tool that requires proper security configuration. This guide provides comprehensive security documentation to help you secure your SPE installation.

Critical Warning: SPE is a powerful tool that should NEVER be installed on Content Delivery (CD) instances or internet-facing servers. Always implement security best practices and follow the principle of least privilege.

Quick Start

New to SPE security? Start here:

- Essential security setup for new installations
- Understand the SPE security model
- Validate your deployment before going live

Security Documentation

Core Security Topics

Understand the two-layer security model that governs SPE:

Application Pool Service Account (OS-level access)
Sitecore User Account (API-level access)
- Application and menu item security

Configure User Account Control to require reauthentication:

How Session Elevation works
Elevation actions (Allow, Block, Password, Confirm)
Token configuration and expiration

Control external access to SPE through web services:

Service descriptions and security implications
Enable/disable individual services
HTTPS and requireSecureConnection

Hardening and Protection

Prevent malicious file uploads:

File type restrictions (extensions and MIME types)
Upload location restrictions
Dangerous file types to never allow

Grant controlled privilege escalation:

How delegated access works
Configuration steps
Use cases (publishing, reports, bulk operations)

Add defense in depth at the web server level:

Deny anonymous access
Windows Authentication
IP address restrictions
SSL/TLS requirements

User Management

Manage Sitecore users and roles:

Bulk user operations
Role queries and management
Item Access Control Lists (ACL)

Deployment and Operations

Deploy only what's needed for CI/CD:

Required files for web services only
Disable UI components
Configuration for automation scenarios

Track security events and detect incidents:

What gets logged
Log levels and configuration
Real-time monitoring strategies

Validation and Compliance

Comprehensive validation before deployment:

Pre-deployment validation
Configuration checklist
Testing procedures
Environment-specific checklists

Security by Environment

Development Environment

Priority: Productivity with basic security

Recommendations:

Session Elevation: Relaxed (Allow or long timeouts)
Web Services: Enable as needed for testing
Logging: DEBUG level for troubleshooting

Start here:

QA/Staging Environment

Priority: Match production security for testing

Recommendations:

Session Elevation: Password or Confirm (5-15 minute timeout)
Web Services: Match production configuration
Logging: INFO level

Start here:

Production Environment

Priority: Maximum security

Recommendations:

Session Elevation: Password or Confirm (3-5 minute timeout)
Web Services: Only handleDownload, client, execution (disable remoting)
Logging: INFO or WARN level

Start here:

CI/CD Environment

Priority: Automation with strict access control

Recommendations:

Minimal Deployment: Use minimal package
Remoting: Enabled with IP restrictions
Web Services: Only required services

Start here:

Security Layers (Defense in Depth)

SPE security uses multiple layers for comprehensive protection:

Each layer provides additional protection. If one layer is compromised, others provide continued security.

Common Security Scenarios

Scenario 1: Locking Down Production CM

Goal: Secure SPE for production content management server

Steps:

Review to understand the model
Configure with 5-minute Password timeout
Disable unnecessary

Scenario 2: Setting Up CI/CD Automation

Goal: Enable remote automation from build servers

Steps:

Use package
Enable Remoting in with specific user
Configure with IP restrictions to build servers

Scenario 3: Delegating Report Access

Goal: Allow content authors to run administrative reports

Steps:

Understand concepts
Create delegated access configuration for reporting role
Configure impersonated user with read-only administrative access

Scenario 4: Identity Server Integration (Sitecore 9.1+)

Goal: Configure SPE with Sitecore Identity Server

Steps:

Enable Spe.IdentityServer.config
Configure with Confirm action (not Password)
Test Console and ISE with federated authentication

Security Best Practices Summary

✅ Do

Always deny anonymous access at IIS level
Always use Session Elevation (UAC) in production
Always require HTTPS for any enabled web services

❌ Don't

Never install SPE on Content Delivery (CD) servers
Never expose SPE to internet-facing servers
Never use elevationAction="Allow" in production

Quick Reference

Configuration Files

File

Purpose

Documentation

Security Policies Location

Policy

Location

Documentation

Default Roles

Role

Default Access

Recommendation

Getting Help

New to SPE Security? Start with
Deploying to production? Use the
Setting up automation? See

Support Resources

GitHub Issues:
Slack: #module-spe on Sitecore Community Slack
Documentation:

Security Incident Response

If you suspect a security breach:

Immediately lock down SPE using
Review logs using guidance
Document the incident

Additional Resources

- Initial SPE installation
- Console, ISE, and Interactive Dialogs
- Using SPE Remoting for automation

External References

Version-Specific Notes

Sitecore 9.1+ with Identity Server

Enable the Identity Server configuration:

File: App_Config\Include\Spe\Spe.IdentityServer.config
Purpose: Prevents infinite loop in SPE Console
Use elevationAction="Confirm" instead of "Password"

Sitecore XM Cloud

Consult the latest SPE documentation for XM Cloud-specific security configurations.

Remember: Security is not a one-time configuration. Regular reviews, monitoring, and updates are essential to maintaining a secure SPE installation.

Last Updated: 2025 Maintained By: SPE Community

Web Services

SPE provides several web services for external access and automation. By default, most services are disabled to minimize the attack surface. This guide explains each service and how to secure them when enabled.

Overview

Web services enable powerful capabilities like:

Remote script execution (SPE Remoting)
RESTful API access
File and media uploads/downloads
Report exports

Security Warning: Only enable web services you specifically need. Each enabled service increases your attack surface. Never enable services on internet-facing servers.

Service Configuration

Services are configured in App_Config\Include\Spe\Spe.config:

Service Descriptions

Client Service (enabled by default)

Service File: PowerShellWebService.asmx

Purpose: Powers the SPE Console and ISE user interfaces.

Required For:

PowerShell Console
PowerShell ISE (Integrated Scripting Environment)

Security Considerations:

Required for basic SPE functionality
Access controlled by Sitecore user permissions
Protected by Session Elevation (UAC)

Should you disable it? No - this breaks the Console and ISE.

Execution Service (enabled by default)

Service File: Various pipeline integrations

Purpose: Checks if users have permission to run SPE applications.

Required For:

Download File dialogs
PowerShell Script Runner
Content Editor integrations (Context Menu, Insert Options, Ribbon)

Security Considerations:

Authorization check service
Does not execute arbitrary code
Validates permissions before allowing access

Should you disable it? No - this breaks SPE integration points.

Handle Download Service (enabled by default)

Service File: RemoteScriptCall.ashx

Purpose: Enables file downloads through the Sitecore interface.

Required For:

Out-Download command
Report exports (CSV, Excel, etc.)
ISE script exports

Security Considerations:

Only works for authenticated users
Requires active Sitecore session
Downloads are temporary and time-limited

Should you disable it? Only if you never need to download files from SPE (rare).

Remoting Service (disabled by default)

Service File: RemoteAutomation.asmx

Purpose: Allows external clients to execute PowerShell scripts remotely.

Required For:

SPE Remoting module
Automated CI/CD scripts
External automation tools

Security Considerations:

⚠️ HIGH RISK - enables remote code execution
Must be protected with role-based authorization
Should require HTTPS

Example Use Case: Automated content deployment from build servers.

Securing Remoting Service

Enable with HTTPS requirement:

Restrict to specific users:

Load Balancer Note: When using requireSecureConnection behind a load balancer that handles TLS termination, you may receive 403 errors. The backend server receives HTTP traffic and .NET doesn't recognize it as secure. Consider network-level security instead.

RESTful v2 Service (disabled by default)

Service File: RemoteScriptCall.ashx

Purpose: Execute scripts via RESTful URLs with all parameters in the URL.

Required For:

PowerShell Web API
RESTful script endpoints
External integrations

Security Considerations:

⚠️ MEDIUM-HIGH RISK - exposes script execution via HTTP
URL-based parameters may be logged
Should require HTTPS

Example Use Case: Providing a web API for external systems to query Sitecore content.

Enabling RESTful v2

File Download Service (disabled by default)

Service File: RemoteScriptCall.ashx

Purpose: Download files from the server file system via URL.

Required For:

SPE Remoting file downloads
External file retrieval

Security Considerations:

⚠️ MEDIUM RISK - exposes file system
Restricted by file type and location configuration
Only works with allowed paths

Should you enable it? Only if using SPE Remoting and need file downloads.

File Upload Service (disabled by default)

Service File: RemoteScriptCall.ashx

Purpose: Upload files to the server file system via URL.

Required For:

SPE Remoting file uploads
External file deployment

Security Considerations:

⚠️ HIGH RISK - allows writing to file system
Restricted by file type and location configuration
Can be used to deploy malicious files if misconfigured

Should you enable it? Only if absolutely necessary, with strict restrictions.

Securing File Upload

See for detailed configuration.

Media Download Service (disabled by default)

Service File: RemoteScriptCall.ashx

Purpose: Download media library items via URL.

Required For:

SPE Remoting media downloads
External media retrieval

Security Considerations:

⚠️ LOW-MEDIUM RISK - exposes media library
Respects Sitecore security
May expose sensitive media items

Should you enable it? Only if using SPE Remoting and need media downloads.

Media Upload Service (disabled by default)

Service File: RemoteScriptCall.ashx

Purpose: Upload files as media library items via URL.

Required For:

SPE Remoting media uploads
External media deployment

Security Considerations:

⚠️ MEDIUM RISK - allows media library uploads
Restricted by file type configuration
Can bloat media library if misused

Should you enable it? Only if using SPE Remoting and need media uploads.

RESTful v1 Service (disabled by default - DEPRECATED)

Service File: RemoteScriptCall.ashx

Purpose: Legacy RESTful API from early SPE versions.

Security Considerations:

⚠️ DEPRECATED - avoid using
Use RESTful v2 instead

Should you enable it? No - migrate to v2.

Configuration Examples

Minimal Configuration (UI Only)

Default configuration - only services needed for Console and ISE:

CI/CD Configuration

Enable remoting for build automation, with strict security:

Web API Configuration

Enable RESTful v2 for web API endpoints:

Full SPE Remoting

Enable all remoting capabilities (use with caution):

Role-Based Authorization

Restrict remoting access to specific roles or users.

Default Authorization

By default, these roles can use remoting (when enabled):

Replace Default Roles

Remove default roles and add your own:

Add Specific Users

Grant access to individual users:

Combine Roles and Users

IIS-Level Protection

Add an additional security layer by configuring IIS authentication.

Deny Anonymous Access

Edit sitecore modules\PowerShell\Services\web.config:

This denies all anonymous users from accessing SPE web services.

Windows Authentication

For environments with Windows Authentication:

Disable Anonymous Authentication in IIS for sitecore modules\PowerShell\Services\
Enable Windows Authentication
Use the Credential parameter in remoting commands:

Best Practices

Security Recommendations

✅ Do:

Only enable services you specifically need
Require HTTPS for all external services (requireSecureConnection="true")
Use role-based authorization to limit access

❌ Don't:

Enable all services "just in case"
Allow HTTP for remoting or file upload
Grant broad role access (e.g., "Everyone")

Environment-Specific Configurations

Environment

Recommended Services

Rationale

Decision Matrix: Should You Enable This Service?

Service

Enable If...

Security Requirements

Troubleshooting

403 Forbidden when using requireSecureConnection

Cause: Load balancer terminates TLS and forwards HTTP to backend.

Solution:

Configure network-level security instead
Remove requireSecureConnection and secure at network/firewall level
Or configure load balancer to forward HTTPS

Remoting returns "Access Denied"

Possible causes:

User/role not in authorization list
IIS denies anonymous access but credentials not provided
User doesn't exist or password is incorrect

Solution: Check configuration and verify credentials.

File upload fails even when enabled

Cause: File type or location not allowed.

Solution: Configure file upload restrictions (see ).

- Configure allowed file types and paths
- Additional IIS-level hardening
- Using SPE Remoting features

References

Minimal Deployment

For CI/CD and automation environments where you only need SPE web services (without the full UI), a minimal deployment reduces the attack surface while maintaining remote automation capabilities.

Overview

The minimal deployment includes only the files necessary to support SPE web services, removing all UI components (Console, ISE, Content Editor integrations).

Benefits:

Smaller attack surface
Fewer files to maintain
Faster deployment
Ideal for build/deployment servers
Only what's needed for automation

Limitations:

No PowerShell Console
No PowerShell ISE
No Content Editor integration
No Reports UI

This deployment is specifically designed for environments that only need remote script execution via SPE Remoting.

Use Cases

CI/CD Environments

Scenario: Build servers need to execute deployment scripts remotely.

Requirements:

Remoting service
Minimal file footprint
No interactive UI

Automated Content Deployment

Scenario: Automated systems deploy content packages to Sitecore.

Requirements:

Remote script execution
File upload capability
Package installation commands

Headless/API-Only Instances

Scenario: Sitecore instances that serve as API backends without content authoring.

Requirements:

Remote automation capability
No UI overhead
Security-focused configuration

Required Files

Core Files

File Path

Purpose

Required

Web Service Files

File Path

Purpose

Required

Excluded Files (Not Needed)

The following are NOT included in minimal deployment:

❌ PowerShell Console UI files ❌ PowerShell ISE files ❌ Content Editor integration files ❌ Report UI files ❌ Gutter renderers ❌ Ribbon extensions ❌ All UI-related files in sitecore modules\Shell\PowerShell\

Installation Steps

Option 1: Using Minimal Package

SPE provides a pre-built minimal package: SPE.Minimal-6.x.zip

Download SPE.Minimal-8.x.zip from SPE releases
Extract to your Sitecore instance
Enable disabled config files (see below)

Option 2: Manual Installation

Deploy required files using your favorite scripting language.

Step 3: Disable UI Control Sources

Create a config patch to disable UI control sources:

File: App_Config\Include\Spe\Custom\Spe.DisableUI.config

Configuration

Enable Remoting Service

By default, Remoting is disabled. Enable it with proper security:

File: App_Config\Include\Spe\Custom\Spe.Remoting.config

Secure Web Services

File: sitecore modules\PowerShell\Services\web.config

Testing the Deployment

Verify Minimal Installation

Security Best Practices

Minimal Deployment Security Checklist

Remoting disabled by default - Only enable when configuration complete
HTTPS required (requireSecureConnection="true")
Anonymous access denied in web.config

Recommended Security Layers

Network - Firewall rules, VPN if possible
IIS - IP restrictions, Windows Auth (optional), HTTPS
Sitecore - Specific user accounts with minimal roles

Troubleshooting

Remoting connection fails

Possible causes:

Remoting service not enabled
User not in authorization list
HTTPS required but using HTTP
Anonymous access denied but not providing credentials

Solution: Check configuration, verify credentials, ensure HTTPS.

UI elements still appear

Cause: controlSources not disabled in configuration.

Solution: Verify Spe.DisableUI.config patch is present and loading.

- Detailed web service configuration
- IIS-level hardening
- Configure upload limits

Sitecore PowerShell Extensions

Introduction

hashtagAbout the Module

Disclaimer

Installation

hashtagPrerequisites

hashtagDocker

hashtagInstallation Wizard

hashtagUpgrade

hashtagFrom 6.x

hashtagFrom 5.x and older

hashtagTroubleshooting

Contributor Guide

hashtagSingle Instance for Sitecore 8 & 9

hashtagMultiple Instances

hashtagOptional: PowerShell Remoting support

hashtagOptional: Junction Support

Interfaces

Console

hashtagShortcuts

Interface Configuration

hashtagColors

Help

hashtagViewing all available commands

hashtagViewing command help

hashtagConsole

hashtagISE

hashtagDocumenting functions

hashtagOnline appendix

Variables

Item Languages

hashtagAdd Language Version

hashtagRemove Language Version

hashtagNew Item with Forced Language Version

hashtagParameters and Configuration

hashtagReferences

Control Panel

hashtagAdministration

hashtagAnalytics

hashtagDatabase

hashtagGlobalization

hashtagPreferences

hashtagReports

hashtagSecurity

Data Sources

hashtagField Data Source

hashtagRendering Data Source Roots

hashtagRendering Data Source Items

hashtagReferences

Event Handlers

Functions

ISE Plugins

hashtagAdd a custom plugin

Pipelines

hashtagLogging In

Tasks

hashtagVideo Tutorial

hashtagScheduled Task Command

hashtagCreate and Manage Tasks

Web API

Workflows

Packaging

hashtagPackage Creation

hashtagPost Step

Users and Roles

hashtagUsers

Troubleshooting

hashtagGeneral

hashtag

Manage Templates

hashtagManage Templates

hashtagChange Template

hashtagSitecore Stack Exchange

Close-Window

hashtagSyntax

hashtagDetailed Description

hashtagParameters

hashtagNotes

hashtagExamples

hashtagEXAMPLE

About the Module

Prerequisites

Docker

Installation Wizard

Upgrade

From 6.x

From 5.x and older

Troubleshooting

Single Instance for Sitecore 8 & 9

Multiple Instances

Optional: PowerShell Remoting support

Optional: Junction Support

Shortcuts

Colors

Viewing all available commands

Viewing command help

Console

ISE

Documenting functions

Online appendix

Add Language Version

Remove Language Version

New Item with Forced Language Version

Parameters and Configuration

References

Administration

Analytics

Database

Globalization

Preferences

Reports

Security

Field Data Source

Rendering Data Source Roots

Rendering Data Source Items

References

Add a custom plugin

Logging In

Video Tutorial

Scheduled Task Command

Create and Manage Tasks

Package Creation

Post Step

Users

General

Manage Templates

Change Template

Sitecore Stack Exchange

Syntax

Detailed Description

Parameters

Notes

Examples

EXAMPLE

Related Topics

Syntax

Detailed Description

Parameters

-InputObject <PSObject>

Inputs

Outputs

Notes

Examples

EXAMPLE

Related Topics

Syntax

Syntax

Detailed Description

Parameters

Outputs

Notes

Examples

EXAMPLE

Related Topics

Syntax

Detailed Description

Prerequisites

Docker

Installation Wizard

Upgrade