First published on TechNet on Sep 17, 2012
Hello, Rick here to talk about how you can use the new PowerShell Web Access (PSWA) feature in Windows Server 2012 to allow remote administrative access to a set of servers in your IT infrastructure. Furthermore, you can granularly delegate access and only expose specific administrative privileges to different levels of support teams in your IT environment. PowerShell Web Access (PSWA) brings great remote manageability in Windows Server 2012. It acts as a gateway to provide full or limited access into the PowerShell sessions on remote servers.
Even with PowerShell tab completion, no one fancies typing cmdlets on their phone. However, if using your phone allows you to be away from your desk while accomplishing a simple task, it’s not a bad option. Additionally, with the coming proliferation of tablets/slates with more functional keyboards, I think you may appreciate this feature a bit more 
Let’s gets started, by installing the feature using the Install-WindowsFeature cmdlet:
Install-WindowsFeature WindowsPowerShellWebAccess –IncludeManagementTools
Next we will add the web application and other required IIS components for PSWA:
Install-PswaWebApplication –WebApplicationName “pswagateway” –UseTestCertificate
Note that PSWA requires by default HTTPS to secure/encrypt the data from your web client to the gateway server. In this example we used the built-in “Test Certificate” functionality which is a self-signed certificate good for 90 days. Test Certificate should NOT be used in production environment. You can refer to guidance on technet on how to setup SSL with external CA or internal PKI for PowerShell Web Access Gateway.
By default, PSWA uses the ‘Default Web Site’ in IIS.
PowerShell Web Access is now installed and can be accessed via the browser. We will type in the URL of the gateway machine with the web application name we used above. You will get the warning that the certificate provided by this website was not issued from the trusted certificate authority due to the test certificate we are using. Select continue, and you will land at the form-based log in page to the PSWA.
Before users log into the PSWA site, we will have to add the authorization rules. PSWA provides four levels of security;
- IIS security which is based on certificates
- Form-based gateway authentication
- Authorization rules (which define which set of users have access to which set of servers)
- Target machine authentication/ Session configuration. This can be used to allow specific users access to a particular set of modules, cmdlets, alias etc, that you can configure as restricted runspaces, or session configurations, for Windows PowerShell Web Access. For example, you could restrict users to only using the PowerShell ActiveDirectory module, and no other modules such as the FailoverClusters module.
In following example we will illustrate giving permissions to ‘Domain Admins’ to all ‘Domain Controllers’ for all PowerShell modules. (All cmdlets on this blog are one liners, please excuse the wrapping).
Add-PswaAuthroizationRule –UserGroupName ‘port389\domain admins’ –ComputerGroupName ‘port389\domain controllers’ –ConfigurationName Microsoft.powershell
Note: My domain name in these examples is “port389”. So when I use “port389” I am referring to a domain, not a specific network port.
The configuration name is where session information is saved. A " session configuration " also known as an " endpoint " is a collection of settings on the local computer that define the environment for Windows PowerShell sessions (PSSessions) that connect to (terminate at) the computer. All PSSessions use a session configuration. To specify a particular session configuration, use the ConfigurationName parameter that exposes a pre-configured session. This defines the level of access from within PowerShell. In the above example we are using a built-in Microsoft.powershell which gives full access to all cmdlets, modules, and providers. Run Help Get-PSSessionConfiguration to learn more and also see this information. More on this later.
So we type in our user ID and password for one of the domain admins and select ‘DC1’ in this test environment and log in.
You can see above how we have access to PowerShell on DC1 just as we would by remoting into it. Note that remoting must be enabled on the target machines. It comes enabled on all domain joined servers in Windows Server 2012. To do a quick check, use the Enter-PSSesion cmdlet from a normal PowerShell window outside of PSWA.
Enter-PSSession –ComputerName Storage1 –Credential $cred
If it needs to be enabled, use the Enable-PSremoting cmdlet. Watch this great TechEd video on remoting in PowerShell v3.
Now let’s create a session configuration file to give user ‘Mark’ access to the Storage module on a server called Storage1. For this we use the New-PSSessionConfigurationFile cmdlet. Note that*PSSessionConfiguration* based cmdlets are part of PowerShell v3 which is part of Windows Management Framework 3.0, which can be downloaded here for older (non-Windows 8 or Windows Server 2012) clients like Windows 7 and Windows Server 2008.
We will log on to the storage server (Storage1) and run the following cmdlet:
New-PSSessionConfigurationFile -ModulesToImport Storage -LanguageMode NoLanguage -SessionType RestrictedRemoteServer -Path StorageOnly.pssc
With the above cmdlet, we are importing the storage module, defining the session type as restricted remote server and filename and path for storing the session configuration file which has an extension of . pssc.
Next we will have to register this session configuration file (still on the target machine – Storage1) where it will be called for an incoming remote session. In the syntax, below, we are giving this config a name (StorageOnly). We are using the –runas parameter to specify the administrative credentials that will be used when this session endpoint is called/created on the target server (Storage1). The syntax also includes the –ShowSecurityDescriptorUI which is a convenient way for modifying the ACL, allowing ‘Mark’ to read and execute this session configuration file (see the 2 nd , screen-shot below).
Finally, we specify the same filename and path for the .pssc file which was created in the previous command.
Register-PSSessionConfiguration -Name StorageOnly -RunAsCredential port389\administrator -ShowSecurityDescriptorUI -Path .\StorageOnly.pssc
Note the warning that with “RunAs” the endpoint will be running under a privileged account (in our case a Domain Admin), so we should restrict the scope of our session configuration in two ways. First, ‘Mark’ is only allowed to use the cmdlets from the Storage PowerShell module (see the New-PSSessionConfigurationFile syntax, above). Second, ‘Mark’ can only read and execute this PowerShell session configuration (see screen-shot, directly above). He can’t modify/write the configuration to grant himself additional privileges. To unregister a PSSessionConfiguration, you can use Unregister-PSSessionConfiguration cmdlet.
Now, we now need to go to our PSWA server and define an authorization rule for Mark, to remotely connect to Storage1 and execute the StorageOnly session.
Add-PswaAuthorizationRule -UserName port389\mark -ComputerName Storage1 -ConfigurationName StorageOnly
Note that in the syntax, above, we must use the same session configuration name (StorageOnly) that we had previously saved/registered on our server (Storage1).
Now, to test our configuration, start at the PSWA web log in page, supply Mark’s username and credentials, then expand the ‘optional connection settings’ section. In the ‘Optional connection settings’ you must provide the name for the session configuration ( StorageOnly) .
Upon login, user Mark will only have access to cmdlets available from the Storage Module on the Storage server and other cmdlets won’t be available.
You can run Get-PswaAuthorizationRule from PSWA machine to take a look at active rules and Remove-PswaAuthorizationRule to remove a rule. Did I mention PowerShell is intuitive :)
Here’s another great way for restricting exactly what your administrators can do via your PSWA infrastructure . Remember above how we created/configured the PSSessionConfiguration on our target server (Storage1). When you create the session with New-PSSessionConfigurationFile , there is an option to expose only a handful of cmdlets via the –VisibleCmdlets parameter (it is wildcard aware). For example, from the screen-shot, above, you can see that when I have created the session configuration for DC2, I only exposed to Mark the Get-ADUser cmdlet, and not the entire library of ActiveDirectory cmdlets. To see which cmdlets are exposed in a PowerShell remote session run:
Get-Command
I would like to point out that session configuration files are not exclusive to PSWA and they can be used with other remoting mechanisms such as Enter-PSSession . You’ll also note that for convenience, non-destructive cmdlets like Exit-PSSession and Get-Help automatically are always added to a session when you define the session type as “restricted remote”.
PSWA sessions will time out after 15 minutes of inactivity, but you can change time-out periods for sessions in the website settings in IIS Manager.
What are the infrastructure requirements?
- Gateway server running Windows Server 2012.
- Target machines running Windows 7, 2008 or 2008 R2 with PowerShell 2.0 and WinRM 2.0 with WinRM enabled.
- Target machines that are Windows 8 or Windows Server 2012 with WinRM enabled.
- Browser compatibility to access the PSWA site, any browser that supports HTML, Java and cookies.
One last nugget for you. PowerShell v3 introduces many great cmdlets that bring more manageability for your Windows infrastructure. One of your favorite new cmdlets will be Show-Command because it helps reduce the PowerShell learning curve. Show-Command will bring up a dialog box that lets you enter parameters in the GUI. Hopefully, it will help you construct your cmdlet with proper syntax and and well-ordered parameters. After constructing your cmdlet, you can either execute it from the dialog box, or copy it to the clipboard.
Conclusion:
PowerShell Web Access combined with *PSSessionConfiguration * cmdlets bring you a great way to manage and delegate permissions for “PowerShell remoting” in your IT department to different levels of support tiers. You can leverage the goodness of Powershell 3.0 and WinRM to centralize access to a group of target servers via a gateway. You can provide ease of access via a web client, and ensure security through proper delegation.
Until next time !
Rick “I would give Mark access to XPERF based cmdlets only, if there were any “ Sheikh