PowerShell Web Access: Reconfiguration

We’re back with our in-depth, multi-part look at PowerShell Web Access (PSWA) on Windows Server 2012. This feature allows you to access a remote PowerShell session via a web browser. The remote computer can be running PowerShell 2, as long as remoting is enabled, or PowerShell v3. The client computer should work with a current version of most major browsers.
In the first article I showed how to install PowerShell Web Access remotely on a new web server from a Windows 8 client running Remote Server Administration Tools (RSAT). In part two, I discussed PSWA configuration, and in part three we learned how to test the PSWA web application. In this final article we’ll reconfigure PowerShell Web Access for use in the domain. So let’s get started!

Removing Test Rules

First, I will remove all of the existing test rules. I will eventually set up some rules for the domain. But for now I’ll double-check the existing rule set from my Windows 8 management desktop using Invoke-Command to remotely run the command on the web server running PSWA.

PS C:\> invoke-command {Get-PSwaAuthorizationRule} -comp chi-web01

You can see the results in Figure 1.
PowerShell Web Access reconfigure
The easy way to remove all of the rules is to pipe them to Remove-PswaAuthorizationrule.

PS C:\> invoke-command {Get-PSwaAuthorizationRule | Remove-PSwaAuthorizationRule -force } -comp chi-web01

The PSWA gateway is still running, but nobody can use it until I add new rules.

Installing a Domain Certificate

PowerShell Web Access was first installed using a test certificate for SSL. If you missed this step, go back to the first article in this series on how to install PSWA. I need to reconfigure the web service to use a valid certificate from my domain certificate service. While it is possible to manage IIS via PowerShell, this is going to be easier to do using the graphical IIS management tools on my Windows 8 box. Note: depending on how you first set up the web server, you may also need to install IIS Management Tools, the IIS Management Service, and configure the server to allow remote management.
On CHI-WEB01, I have installed a web server certificate issued from my domain CA. I need to adjust the site bindings to use this certificate. In the IIS Manager I select the site and edit bindings as you can see below in Figure 2.
PowerShell Web Access site bindings
Now I’ll select the https binding, then click Edit.
PowerShell Web Access site binding
In the above image you can see that I selected the CHI-WEB01 certificate I installed. Now when I open a browser and connect to https://chi-web01/pswa/en-US/logon.aspx I can get a secure connection (as shown below) without any certificate warnings.
PowerShell Web Access reconfigure
You could follow these manual steps when you first set up PSWA. Run Install-PswaWebApplication on the web server and then manually configure the certificate. But you will want to setup an SSL certificate trusted by members of your domain.

Creating Domain Rules in PSWA

Next, I need to create the necessary authorization rules. The rules must be established ON the web server, so I’ll use remoting with Credssp since the command will need to make a second hop to access Active Directory.

PS C:\> enter-pssession chi-web01 -Authentication Credssp -Credential globomantics\jeff

The first rule I’m creating will allow members of the Domain Admins group access to any computer using the Microsoft.PowerShell endpoint.

[chi-web01]: PS C:\> Add-PswaAuthorizationRule -rulename DomainAdmins -usergroupname "globomantics\domain admins" -computername * -configurationname microsoft.powerShell -force

This should provide domain admins full remote PowerShell access.
I also want to give members of the DBA group access to the SQL Server — but only to that server.

[chi-web01]: PS C:\> Add-PswaAuthorizationRule -rulename SQLDBA -usergroupname "globomantics\chicago dba" -computername CHI-DB01 -configurationname microsoft.powerShell -force

The last rule I want to create is to a pre-established constrained endpoint. This endpoint, on CHI-FP01, allows members of the Help Desk group to solve file and share problems using PowerShell.

[chi-web01]: PS C:\> Add-PswaAuthorizationRule -rulename HelpDesk -usergroupname "globomantics\help desk" -computername CHI-FP01 -configurationname FileMgmt -force

PSWA now has three rules.

[chi-web01]: PS C:\> get-PswaAuthorizationRule

You can see them in Figure 5.
PowerShell Web Access reconfigure

Testing Rules in PowerShell Web Access

When you create a new rule, PSWA won’t complain if you use duplicate rule names, and it also doesn’t verify any of the information you specify other than verifying the user or group in Active Directory. There is also no cmdlet to modify an existing rule so if you make a mistake, use Remove-PswaAuthorizationRule to delete and recreate it.
To verify your rules you can use Test-PswaAuthorizationRule. Specify a user name or group, a computer, and optionally a configuration endpoint name.

[chi-web01]: PS C:\> Test-PswaAuthorizationRule -username "globomantics\jeff" -computer chi-dc02

If a valid rule is found, it will be displayed as shown below.
PowerShell Web Access reconfigure
The first two rules check out. But the last rule for the constrained endpoint did not because nothing was returned. But I can try again, and this time I’ll specify a configuration name.

[chi-web01]: PS C:\> Test-PswaAuthorizationRule -username "globomantics\adeco" -computer * -configuration *

Figure 7 below shows the rule.
PowerShell Web Access reconfigure
But let me be clear: All we did was verify that a rule exists for a given user or group. It does not verify that the endpoint was entered correctly, that the server is accessible, or that the account even has the necessary permissions. You need to separately and manually test these things using a cmdlet like Enter-PSSession. If it works there, it should work in PowerShell Web Access.

PSWA: Other Steps to Take

Don’t forget you will need to provide some training and guidance on how to use PowerShell Web Access. If the users are already using PowerShell remoting this transition shouldn’t be too difficult. For domain computers everything should just work. For everything else you might need to tackle some of these tasks, including:

  • Configure the hosts file on non-domain devices, like Android tablets, to resolve the PSWA server name.
  • Install domain CA certificate as a trusted root on non-domain devices.
  • Configure public-facing access to PSWA so that you can remotely manage servers from outside your corporate walls.
  • Maintain close watch on group memberships that have remote access permissions.

The specifics naturally will vary depending on your situation.
PowerShell Web Access can be a very potent tool in your management portfolio, but take the time to set up domain-oriented rules and procedures. Use the Test-PswaAuthorization rule to troubleshoot access issues. Use Enter-PSSession to troubleshoot other remoting configuration problems.