PowerShell Web Access - PowerShell in Depth, Second Edition (2015)

PowerShell in Depth, Second Edition (2015)

Appendix B. PowerShell Web Access

PowerShell Web Access (PWA) was introduced as part of Windows Server 2012 and enhanced in Windows Server 2012 R2. Strictly speaking, it isn’t part of PowerShell but is a feature of Windows Server that enables you to connect to a PowerShell Remoting endpoint from a web browser. That web browser can be on a Windows device, a non-Windows tablet, on even a smart phone if your eyesight is good enough to deal with the tiny screen. PWA brings mobile remoting to administrators using PowerShell. In this appendix, we’ll give you an overview of setting up PWA and then conclude by working through a script that will set up PWA on a remote machine.

The first thing you need to do is install PWA. The PWA server would normally sit in your organization’s DMZ. Connectivity is supplied to the corporate LAN so that you can create remote connections from the PWA server to machines in your domain. In this first example, we assume that the machine is in the domain.

PWA is a Windows feature and isn’t installed by default. You also need to ensure that IIS, .NET 4.5, and PowerShell 3.0 (Windows Server 2012), 4.0 (Windows Server 2012 R2), or 5.0 (the next version of Windows Server) are installed.

You can use Server Manager to perform the install or better still use PowerShell:

Install-WindowsFeature -Name WindowsPowerShellWebAccess `

-IncludeAllSubFeature -IncludeManagementTools -Restart

This code will install PWA and the required subfeatures, and then force the machine to restart. The supporting roles and features should be installed for you. If you want to ensure you have full control over the install process, you can specifically state what you want installed:

Install-WindowsFeature -Name Web-WebServer, Web-Mgmt-Console,

NET-Framework-45-ASPNET, Web-Net-Ext45, Web-ISAPI-Ext,

Web-ISAPI-Filter, Web-Default-Doc, Web-Http-Errors,

Web-Http-Redirect, Web-Static-Content,

Web-Filtering, WindowsPowerShellWebAccess -Confirm:$false

The installation routine adds a PowerShell module for managing PWA:

PS C:\> Get-Command -Module PowerShellWebAccess

CommandType Name

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

Function Install-PswaWebApplication

Function Uninstall-PswaWebApplication

Cmdlet Add-PswaAuthorizationRule

Cmdlet Get-PswaAuthorizationRule

Cmdlet Remove-PswaAuthorizationRule

Cmdlet Test-PswaAuthorizationRule

These cmdlets exist to test and administer the PWA service. You still need to have the correct modules, or scripts, installed on the machines you’re going to manage via PWA.

Your next step is to create the PWA web application:

Install-PswaWebApplication -WebApplicationName PSG `

-UseTestCertificate

Give the application a name and in this case use a self-generated test certificate.

Warning

Do not use this technique in a production environment; use a proper SSL certificate.

You now need to add a rule to enable a user or group to access a server:

Add-PswaAuthorizationRule -RuleName "RS Server 02 Full" `

-ComputerName server02.manticore.org `

-UserName manticore\richard `

-ConfigurationName microsoft.powershell

This command has created a rule that allows a user called Richard to access the default remoting endpoint on an individual server—in this case, server02. No other users can access that endpoint and server pairing through PWA until they are explicitly granted the rights to do so. To minimize administration, use groups rather than individuals.

This is an important point and needs to be repeated. Users (or groups of users) are explicitly granted access through PWA to specific remoting endpoints on specific servers. If you aren’t part of a PWA authorization rule, either individually or through a group, you don’t get access. If you attempt to access a server through PWA where a rule doesn’t exist to give you access, your connection attempt will be refused by the system. If you look at the syntax of Add-PswaAuthorizationRule, you’ll see that you can use groups of computers as well as groups of users:

PS C:\> Get-Command Add-PswaAuthorizationRule -Syntax

Add-PswaAuthorizationRule -ComputerGroupName <string>

-ConfigurationName <string> -UserGroupName <string[]>

[-Credential <pscredential>] [-RuleName <string>]

[-Force] [<CommonParameters>]

Add-PswaAuthorizationRule [-UserName] <string[]>

-ComputerGroupName <string> -ConfigurationName <string>

[-Credential<pscredential>] [-RuleName <string>]

[-Force] [<CommonParameters>]

Add-PswaAuthorizationRule -ComputerName <string>

-ConfigurationName <string> -UserGroupName <string[]>

[-Credential<pscredential>] [-RuleName <string>]

[-Force] [<CommonParameters>]

Add-PswaAuthorizationRule [-UserName] <string[]>

[-ComputerName] <string> [-ConfigurationName] <string>

[-Credential<pscredential>] [-RuleName <string>]

[-Force] [<CommonParameters>]

Consult the cmdlet documentation (remember to use Update-Help) for full details.

You can examine the rules enabled on a PWA box:

PS C:> Get-PswaAuthorizationRule | Format-List *

Id : 0

RuleName : RS Server 02 Full

User : manticore\richard

UserType : User

Destination : manticore\server02

DestinationType : Computer

ConfigurationName : microsoft.powershell

And you can test those rules:

Test-PswaAuthorizationRule -ComputerName server02 `

-UserName manticore\richard

This command tests whether a particular user can access a particular computer through PWA. If the answer is yes, you see the rule information; otherwise, no data is returned.

If you install PWA on a computer called Win12R2, you can access it like this:

https://win12r2/PSG

where PSG is the name of the web application that we created earlier. When accessing PWA, you’ll have to log in with your credentials and give the name of the server to which you’ll connect. PWA connections are made to a single server at a time. You can’t get access to multiple servers because you’re connecting to specific remoting endpoints on specific servers. Figure B.1 shows the PWA logon screen.

Figure B.1. Logging into PowerShell Web Access

In figure B.1 one set of credentials is supplied. These are domain credentials that allow access to all computers in the domain. If you’re accessing non-domain-joined computers, or you’re using local accounts for any reason, you’ll need to supply appropriate credentials for the server to which you’re connecting.

Your browser will display a PowerShell console with an area at the bottom to type your commands and a results pane above it, as shown in figure B.2.

Figure B.2. Using PowerShell Web Access

Note

Tab completion doesn’t fully work in the PWA console. It works for cmdlet names but not other items, such as environment variables or cmdlet parameters.

The PWA console has an Exit button in the bottom-right corner that you click to close the connection (see figure B.2). You’ll be returned to the logon screen (figure B.1). You can then close the browser or connect to another machine.

So far you’ve exposed the whole of the functionality available through PowerShell to the user via PWA. You may want to limit the activities the user can perform, in which case you need to create a constrained endpoint as you saw in chapter 10. As an example, assume you have a constrained endpoint that provides access only to the Active Directory cmdlets. To make this available through PWA, you need to create a rule:

Add-PswaAuthorizationRule -RuleName "server02 AD admin only" `

-ComputerName server02.manticore.org `

-UserName manticore\methul -ConfigurationName ADPS

If you test the rule:

Test-PswaAuthorizationRule -UserName manticore\methul `

-ConfigurationName * -ComputerName server02

you’ll see that the user is granted access to only the ADPS configuration on server02.

When users sign in to PWA, they have to enter the specific endpoint they want to access. Running Get-Command shows the limited functionality available through the endpoint.

PWA has a lot more options that you can discover in the documentation at http://technet.microsoft.com/en-us/library/hh831611.aspx. We strongly recommend reading this documentation before implementing PWA.