PowerShell Web Access: Configuration

by Jeff Hicks - January 3, 2013

We're back with our look at Powershell Web Access (PSWA), a multi-part series in which I walk you through the installation, configuration, testing, and reconfiguring PSWA for use in the domain. Powershell Web Access -- a web-based application -- allows you to establish a remote PowerShell session via a web browser. With PSWA you are able to remotely manage servers from a machine that doesn’t even have PowerShell installed on it, such as a Mac or Android tablet.

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 three I'll show you how to test the PSWA web application, and in the final article we’ll reconfigure PowerShell Web Access for use in the domain.

PSWA and Gateway Configuration

You could run the necessary commands on the server, but I prefer remote management. I’ll open a remote PowerShell session to the server from my Windows 8 desktop.

PS C:\> enter-pssession CHI-WEB01

For now, I’m going to configure the gateway to use a self-signed test certificate. Later the website can be configured to use a valid certificate.

[chi-web01]: PS C:\> Install-PswaWebApplication –usetestcertificate

This command assumes I haven’t changed the default web site name (“Default Web Site”) or application name (“pswa”). Figure 1 depicts the result.

 

Configure Gateway Powershell Web Access

I can’t think of a good reason to modify the application name. The application is secure out-of-the-box.

Advertisement

Configuring Authorization Rules with PSWA

By default, nobody has access to PowerShell Web Access. You must define authorization rules using the Add-PswaAuthorizationRule cmdlet. This too must be run on the web server, so I’ll use my existing remote session. You will need to specify a user name or user group that want to grant access to, the names of computers that you want to allow remote access to (you can also use a group name that contains computer accounts), and the configuration name.

The configuration is the name of a remoting endpoint. The PowerShell Web Access gateway will establish a remote connection to this endpoint. You can use Get-PSSessionConfiguration to enumerate the sessions.

PS C:\> invoke-command {get-pssessionconfiguration} -ComputerName chi-dc03

Figure 2 below shows the available endpoints on CHI-DC03.

 

Configure Powershell Web Access

 

The session configuration must exist on all computers in your rule. I’m going to create a test authorization rule using the Microsoft.PowerShell configuration. This is essentially the end point you get with a regular remoting session. Optionally, you can define a rule name, as I’ve done here.

[chi-web01]: PS C:\> Add-PswaAuthorizationRule -rulename "Test Rule 1" -computername chi-dc03 -username globomantics\jeff -configuration microsoft.powershell

But wait a moment -- if you try this on a new system, you’ll most likely get an error like this:

Add-PswaAuthorizationRule : This command must be run by a user account with permissions to perform Active Directory queries.

If you run the command in an interactive (i.e. not via remoting) session on the server it should work just fine. The problem here is the second hop. The Add-PSwaAuthorizationRule cmdlet needs to make a connection to a domain controller, which by security design is not allowed in PowerShell Remoting. This second-hop limitation can be overcome by enabling CredSSP authentication. Note: This is not be done lightly as there are security ramifications, so research this fully before employing.

But in my situation, since I want to use remoting, I’ll exit out of the remote session and enable CredSSP on my desktop for CHI-WEB01.

PS C:\> Enable-WSManCredSSP -DelegateComputer chi-web01 -Role Client

Next, I need to enable the server side.

PS C:\> invoke-command {enable-wsmancredssp -Role Server -Force} -ComputerName chi-web01

With this in place, I can now re-establish my remote session specifying CredSSP and my credentials.

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

Now when I run the authorization command, it works as you can see below in Figure 3.

 

Configure Powershell Web Access

I can also verify the rule:

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

Id  RuleName     User               Destination          ConfigurationName

--  --------     ----               -----------          -----------------

0   Test Rule 1  globomantics\jeff  globomantics\chi...  microsoft.powers...

You can add as many different authorization rules as you need. You can connect to PowerShell v2 machines as long as they have remoting enabled. Here, I’ll add a rule to a domain controller still running PowerShell v2.

[chi-web01]: PS C:\> Add-PswaAuthorizationRule -rulename "Test Rule 2" -computername chi-dc02 -username globomantics\jeff -configuration microsoft.powershell –force

To delete a rule use Remove-PwaAuthorizationRule. Specify the rule by id or the rule object.

[chi-web01]: PS C:\> Remove-PswaAuthorizationRule -id 1 -whatif

What if: Performing operation "Remove-PswaAuthorizationRule" on Target "Rule 'Test Rule 2' (ID: 1)".

[chi-web01]: PS C:\> Get-PswaAuthorizationRule "test rule 2" | Remove-PswaAuthorizationRule –force –whatif

What if: Performing operation "Remove-PswaAuthorizationRule" on Target "Rule 'Test Rule 2' (ID: 1)".

 

All of the PowerShell Web Access configuration settings that I’ve covered can also be done manually via the GUI in the IIS manager. But frankly, that is a lot of point-and-click work that is very prone to error. I’m assuming that if you are setting up PowerShell Web Access that you already are comfortable with PowerShell. The configuration cmdlets need to be run on the web server hosting the PSWA application. But you can use PowerShell remoting to effect the changes, although you might need to enable CredSSP for part of the process. In the next part of the series we’ll look at testing and using PSWA.

 

Advertisement



Join The Petri Insider - Weekly IT Tutorial and Tips, Whitepaper and Webinars