Learn about Windows PowerShell
Summary: Richard Siddaway explains how to secure Windows PowerShell remoting sessions.
Hey, Scripting Guy! I’ve just starting learning Windows PowerShell, and I understand how to use it as a scripting language and shell on the local machine. How do I work with remote machines?
Honorary Scripting Guy, Richard Siddaway, here today filling in for my good friend, The Scripting Guy. This is the fourth part of a series of five posts about remoting:
You have seen how you can access remote systems by using the ComputerName parameter of various cmdlets. This is very good for ad hoc work, or if you need to access a remote machine to perform a single task. When you need to access multiple machines multiple times, you need to use Windows PowerShell remote sessions to give you a reusable connection that is more efficient overall.
In the third part of this series, you learned about:
These have one thing in common: They can be used to make your remoting session more secure. Please note that I’m not suggesting that the default configuration is insecure. I have heard of many organizations refusing to allow enabling remoting because they think it compromises the security of their servers. Windows PowerShell and remoting does not give you any more permissions than you have already. If you use RDP to remote into a Windows system, you can only perform actions that your credentials allow. Exactly the same is true of Windows PowerShell and remoting—you can only perform those actions for which you have permissions.
That’s not the end of the story. You can use the information on configuring endpoints from last time to create your own custom endpoints. These endpoints can be locked down to add further control for who can access them and what they can do once they have access. This is in addition to the normal Windows security.
You can take any endpoint and remote in to it through Windows PowerShell Web Access. This provides Windows PowerShell in a browser through your endpoint to enable remote access into your environment from the comfort of your own home—or anywhere else you can get an Internet connection.
First we need to create a custom endpoint. As an example, lets create an endpoint that gives access only to the Active Directory cmdlets:
New-PSSessionConfigurationFile -Path c:\scripts\config\RestrictedPSAD.pssc -LanguageMode Restricted -Description "Access to AD cmdlets" -ExecutionPolicy Restricted -ModulesToImport 'Microsoft.PowerShell.Utility', ActiveDirectory -PowerShellVersion 3.0 -SessionType RestrictedRemoteServer -VisibleCmdlets 'Read-Host', *AD*
Things to note about this configuration:
You could lock this down so that only Read-Host, Get-AdUser, and Set-ADAccountPassword are available in an endpoint. This would allow a junior administrator to remote in to reset a user’s password, but not perform any other actions. You can find more details about session configuration files in the cmdlet Help file and the about_session_configuration_files Help file.
You now have to register the configuration to create the endpoint:
Register-PSSessionConfiguration -Path c:\scripts\config\RestrictedPSAD.pssc -Force -Name ADPS
Notice that I’ve used a different name for the endpoint from the file. This is recommended. You can test the endpoint’s existence:
£> Get-PSSessionConfiguration -Name ADPS
Name : ADPS
PSVersion : 3.0
Permission : BUILTIN\Administrators AccessAllowed, BUILTIN\Remote Management Users AccessAllowed
This endpoint allows administrators to remote into the system and access the Active Directory cmdlets. No other functionality is available to them. This is a good way to create a separation of duties scenario for your admins. In addition to accessing this endpoint remotely, you can access it (or any other remoting endpoint) with Windows PowerShell Web Access.
PowerShell Web Access was introduced in Windows Server 2012 and enhanced in Windows Server 2012 R2. You can access a remoting endpoint through a browser and run Windows PowerShell commands against that remote system.
Sorry, but when you implement Windows PowerShell Web Access, things are just a tiny bit more complicated than that.
The first thing you need to do is install Windows PowerShell Web Access. It’s a Windows feature, and it isn’t installed by default. You also need to ensure that the following features are installed:
You can use Server Manager to perform the installation—or better still, use Windows PowerShell:
Install-WindowsFeature -Name WindowsPowerShellWebAccess -IncludeAllSubFeature -IncludeManagementTools -Restart
The supporting roles and features should be installed for you. If you want to ensure that you have full control over the installation process, you can specifically state what you want to install:
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 adds a Windows PowerShell module for managing Windows PowerShell Web Access:
£> Get-Command -Module PowerShellWebAccess
Your next step is to create the Windows PowerShell Web Access web application:
Install-PswaWebApplication -WebApplicationName PSG -UseTestCertificate
Give the application a name, and in this case, use a self-generated test certificate. Do not do this 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 creates a rule that allows a user named Richard to access the default remoting endpoint on an individual server. No other users can access that endpoint and server pairing through Windows PowerShell Web Access until they are explicitly granted the rights to do so.
To minimize administration, you are advised to use groups rather than individuals. If you look at the syntax of the Add-PswaAuthorizationRule, you will see that you can use groups of computers or groups of users:
£> 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 Windows PowerShell Web Access box:
£> 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 these rules:
Test-PswaAuthorizationRule -ComputerName server02 -UserName manticore\richard
This command tests if a particular user can access a particular computer through Windows PowerShell Web Access. If the answer is “Yes,” you see the rule information; otherwise, no data is returned.
I’ve installed this on a computer called Win12R2, so can access Windows PowerShell Web Access like this:
…where PSG is the name of the web application that was created earlier. When accessing Windows PowerShell Web Access, you sign in with your domain credentials and provide the name of the server to which you will connect.
Your browser will display a Windows PowerShell console with an area at the bottom to type your commands and a results pane above it.
Note Tab completion doesn’t fully work in the Windows PowerShell Web Access console. It works for cmdlet names, but not for items such as environment variables or cmdlet parameters.
The Windows PowerShell Web Access console has an Exit button in the bottom right corner to close the connection. You can then close the browser or connect to another machine.
So far, you’ve exposed the whole of the functionality available through Windows PowerShell to the user via Windows PowerShell Web Access. You may want to limit the activities the user can perform. In this case, you need to create a constrained endpoint, as you saw in the ADPS endpoint created earlier.
To make this available through Windows PowerShell Web Access, 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 as follows, you will see that the user is granted access only to the ADPS configuration on server02:
Test-PswaAuthorizationRule -UserName manticore\methul -ConfigurationName * -ComputerName server02
When users sign in to Windows PowerShell Web Access, they must enter the specific endpoint that they want to access. Running Get-Command shows the limited functionality available through the endpoint.
Windows PowerShell Web Access has more options, and you can discover them in the following topic: Install and Use Windows PowerShell Web Access.
I strongly recommend reading this before you implement Windows PowerShell Web Access. You can discover more about configuring remoting and some other edge cases in Chapter 10 of PowerShell in Depth by myself, Don Jones, and Jeffery Hicks.
Bye for now.
Thanks, Richard! I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at email@example.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy