PowerShell Universal supports being hosted in IIS (Internet Information Services (IIS) for Windows® Server). Please note that a series of host prerequisites and specific configuration steps are required to facilitate running PowerShell universal on IIS. Please review each section carefully as IIS requires many specific configuration settings applied to work with modern .NET Core applications such as PowerShell Universal.
The following components are required in order to host PowerShell Universal on IIS.
Including: WebSocket Protocol
The following Windows Server IIS features are also required to be enabled on the IIS Host:
Feature Display Name
Required to run PowerShell Universal
Required for using Windows Authentication
First make sure to enable the IIS feature on Windows Server and then install the ASP.NET Core hosting bundle.
NOTE: IIS often requires a host reboot after installing the .NET Core Hosting bundle! It is strongly recommended that you REBOOT the IIS host after installing the .NET Core Hosting bundle.
Once these prerequisites are met, you are ready to begin configuration of PowerShell Universal on IIS.
Download the Latest copy of PowerShell Universal. You will need to download the ZIP Archive version of PowerShell Universal. This archive is specifically built for those wishing to configure PowerShell Universal for IIS or other third party web servers. Extract the contents of the Zip to the intended web host folder location on your IIS Host.
Now that our Host is ready and we have downloaded PowerShell Universal, we can begin configuring IIS.
The First step in the IIS configuration process is to create a new Application Pool in IIS. Before we begin the configuration we should ensure that we select a valid identity for the IIS Application Pool.
The Application Pool Identity is crucial for PowerShell Universal as this will be the "default user" that jobs and dashboards will run as. It will also be the user that will perform read/write operations to the Universal Automation database and will be used by IIS to read the web content directory and execute the application.
It is suggested to use "LocalSystem" or a Service Account of your choosing.
Due to limitations in IIS, the Application Pool Identity settings have MAJOR consequences on the behavior for "Run As" options when using Universal Automation.
Service Account Identity Requirements
Full Read/Write access the PowerShell Universal Application Folder we extracted in Step 2
Full Read/Write access to the PowerShell Universal Database : Default: C:\ProgramData\Universal Automation
Log on as a batch job rights (e.g. from secpol.msc > Local Policies > User Rights Assignment
Once we have selected a valid identity we are ready to create the Application Pool in IIS.
Now that we have chosen an App Pool identity that has read/write access to the PowerShell Universal Application and Database folders we can create the Application Pool in IIS.
In IIs Manager, Choose the option to Add Application Pool...
Name: Use any Name you would like for the Application Pool
.NET CLR Version: No managed code
Click OK create the Application Pool.
Now that the Application Pool has been created, we will need to configure the Advanced Settings
Open the "Advanced Settings" for the Application Pool and apply the following Configurations:
General / Enable 32-Bit Applications: False
Process Model / Identity: Use the Identity we selected for our Application Pool in the "Choosing an App Pool Identity" section above.
Process Model / Load User Profile: True
Once the Advanced Settings have been applied, our Application Pool is ready, our next step will be to configure the IIS Web Site that will utilize this Application Pool.
Now that we have a valid Application Pool we need to create an IIS website to expose the application. Before we do this we will want to review the PowerShell Universal
web.config file for our website. Within the extracted PowerShell Universal Application folder, we will find a web.config file. This configuration file has been specifically designed for IIS and has a number of configurations we need to review prior to creating the IIS Website.
Most Importantly we will need to update "processPath" argument value of this configuration file. This value will provide IIS with the exact path of the application binary so that it can properly launch the application.
Open the web.config file in the PowerShell Universal Application Folder
Locate the <aspNetCore processPath section of the configuration file
Update the arguments="PATH" value to be the exact location of the Universal.Server.dll path.
Save the file to apply the configuration
<?xml version="1.0" encoding="utf-8"?><configuration><system.webServer><handlers><add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /></handlers><aspNetCore processPath="C:\Program Files (x86)\Universal\Universal.Server.exe" arguments="" forwardWindowsAuthToken="false" stdoutLogEnabled="true" stdoutLogFile=".\logs\log" hostingModel="InProcess"/></system.webServer></configuration>
Now that an Application Pool has been created for PowerShell Universal with a valid Identity and we have configured the web.config file, we are finally ready to create the IIS Website. The Website component of IIS loads the application artifacts and exposes the application on the configured web endpoint.
In the IIS Manager: Click "Add Website.."
Configure the new website options :
Site Name: Use any name you would like, ex:
Application Pool: DO NOT use the DefaultAppPool - Select the Application Pool we created in our previous step.
Physical Path: This must be the physical path to the PowerShell Universal Content we extracted from our download .zip file. NOTE: The AppPool identity must have access to the location.
Binding Settings: Note, for initial configuration is suggested to use the base defaults, we'll update these later in our advanced configuration
Type http - For Initial Configuration
IP Address: All Unassigned
Host Name: Name of the Host
At this point, all the required configurations should be in place, and the IIS website hosting PowerShell Universal should be up and running. With a web browser - browse to the configured website location to validate that PowerShell Universal has started. From here you can follow the "Getting Started" guide to validate base functionality. Once you are sure that the Application is working properly with a Basic IIS configuration you can proceed to the "Advanced Configuration" to secure and finalize your desired IIS Configuration.
The settings within the Universal web.config can be adjusted as you see fit. Below you will find a description of each setting.
This setting is used for Windows Authentication. If you wish to use Windows Authentication with IIS, ensure that you disable Anonymous Authentication and enable Windows Authentication within your IIS site and then set this setting to true.
This setting is used for debugging start up issues with your Universal setup. It's recommended to enable this when first configuring IIS integration. You can disable it once everything is configured. You need to ensure that your AppPool identity has write access to the StdOutLogFile location.
The hosting model sets how the Universal server will run. When set to InProcess, the Universal Server will run from within the IIS agent. This provides better performance than using OutOfProcess hosting. InProcess hosting does not work with StdOutLogEnabled. It's recommended to use OutOfProcess hosting only while configuring Universal and, InProcess when your configuration steps have been completed.