An Introduction to PowerShell Remoting Part Five: Constrained PowerShell Endpoints

An Introduction to PowerShell Remoting Part Five: Constrained PowerShell Endpoints

  • Comments 4
  • Likes

Summary: Guest blogger, Jason Hofferle, talks about creating constrained Windows PowerShell endpoints.

Microsoft Scripting Guy, Ed Wilson, is here. Today is the exciting conclusion to Jason Hofferle’s excellent series of articles about Windows PowerShell remoting. I think today’s article is the most important of the bunch – because it illustrates a killer security feature. Here is Jason to tell you about creating constrained Windows PowerShell endpoints.

Photo of Jason Hofferle

Jason Hofferle has been an IT professional since 1997. His experience includes enterprise desktop engineering for a Fortune 500 financial institution and Active Directory design for local governments and law enforcement. Jason currently works for the Defense Contract Management Agency, where he implements new technology such as virtual desktop infrastructure. He recently has been speaking about Windows PowerShell at SQL Saturday and IT Pro Camp events in Florida, and he frequently attends the Tampa PowerShell User Group.

Blog: Force Multiplication through IT Automation
Twitter: @jhofferle

In Part Four of this series, Sessions and Implicit Remoting, I talked about PowerShell sessions and implicit remoting, which allows commands to behave like they are being run locally when they are actually being run transparently on a remote system. In the final blog in this series, I’m going to discuss constrained endpoints, which allow me to control exactly what cmdlets can be used when I am connected to a remote computer.

When I use remoting to connect to a computer, I’m connecting to an endpoint. The Get-PSSessionConfiguration cmdlet enables me to view the currently registered endpoints. When I use Set-PSSessionConfiguration with the ShowSecurityDescriptorUI parameter, I can view the permissions for an endpoint. The default Windows PowerShell endpoints only allow access to members of the local administrators group. These permissions can be modified, or entirely new endpoints can be created.

So why would I want to create a new endpoint? It’s useful for delegation, because not only can I allow others to connect to that endpoint without granting them administrative rights to the computer, but I can also control precisely what commands they are allowed to run on that endpoint. Each endpoint can have an associated startup script that runs whenever a connection is made to that endpoint. The startup script can be used to automatically run commands, load modules, or constrain the session to limit what it can be used for.

Let’s say I want to grant my Help Desk staff access to run some commands on a server. First I’m going to create a startup script that will constrain the session. I start by restricting the session to the point where it’s useless, and then expose only what’s required for the session to work properly, with the commands that I want my Help Desk to be able to view.

foreach ($command in Get-Command)

{

    $command.Visibility = "private"

}

 

foreach ($variable in Get-Variable)

{

    $variable.Visibility = "private"

}

 

$ExecutionContext.SessionState.Applications.Clear()

$ExecutionContext.SessionState.Scripts.Clear()

$ExecutionContext.SessionState.LanguageMode = "NoLanguage"

 

$InitialSessionState =

  [Management.Automation.Runspaces.InitialSessionState]::CreateRestricted(

    "remoteserver")

foreach ($proxy in $InitialSessionState.Commands | where { $_.Visibility -eq "Public"})

{

    $cmdlet = Get-Command -Type cmdlet -ErrorAction silentlycontinue $proxy.name

    if ($cmdlet)

    {

        $alias = Set-Alias "$($proxy.name)" "$($cmdlet.ModuleName)\$($cmdlet.Name)" -PassThru

        $alias.Visibility = "Private"

    }

    Set-Item "function:global:$($proxy.Name)" $proxy.Definition

}

In Bruce Payette’s book, Windows PowerShell in Action 2nd Edition, he uses the InitialSessionState .NET class as an easy way to expose the cmdlets that are required for the session to function correctly. Up to this point, his code is boilerplate that can be used to constrain any endpoint. Now I can start exposing the commands that I want my Help Desk to see. One way to expose certain cmdlets is to change their visibility back to public.

$allowedCmdlets = @("Get-Date","Format-Wide")

Get-Command | Where-Object {$allowedCmdlets -contains $_.Name} |

    foreach {$_.Visibility = "Public"}

If I want to expose an executable or a script, it needs to be added to the endpoint’s list of allowed applications, by using a different method.

$ipConfig = (Get-Command ipconfig.exe).Definition

$ExecutionContext.SessionState.Applications.Add($ipConfig)

Custom functions can also be defined in the startup script. What’s interesting about this is that the staff connecting to this endpoint will have access to the function, but they won’t be able to use the cmdlets inside the function.

Function Get-ServerInfo

{

    $CS = Get-WmiObject -Class Win32_ComputerSystem

    $OS = Get-WmiObject -Class Win32_OperatingSystem

    $Printer = Get-WmiObject -Class Win32_Printer

    $MappedLogicalDisk = Get-WmiObject -Class Win32_MappedLogicalDisk

 

    $Result = New-Object PSObject -Property @{

        UserName = $CS.UserName

        ComputerName = "$($CS.DNSHostName).$($CS.Domain)"

        OSArchitecture = $OS.OSArchitecture

        OSName = $OS.Caption

        OperatingSystemVersion = $OS.Version

        OperatingSystemServicePack = "$($OS.ServicePackMajorVersion).$($OS.ServicePackMinorVersion)"

        DefaultPrinter = ($Printer | Where-Object {$_.Default}).Name

        TypeOfBoot = $CS.BootupState

        LastReboot = $OS.ConvertToDateTime($OS.LastBootUpTime).ToString()

        Drive = $MappedLogicalDisk |

            Select-Object @{Name='Drive Letter';Expression={$_.DeviceID}},

            @{Name='Resource Path';Expression={$_.ProviderName}}

    }

   

    Write-Output $Result

}

With my startup script finished, I can use Register-PSSessionConfiguration to create a new endpoint called HelpDesk.

Register-PSSessionConfiguration –Name HelpDesk –StartupScript C:\StartupScript –Force

Image of command output

Now I can use Set-PSSessionConfiguration to grant access to my Active Directory group HelpDesk to allow them to use remoting commands to connect to the endpoint.

Set-PSSessionConfiguration –Name HelpDesk –ShowSecurityDescriptorUI –Force

Image of command output

Now that the PowerShell Remoting endpoint has been constrained with a startup script, my Help Desk staff can access the endpoint, and they’ll only see the commands that are available to them.

Image of command output

This is also an ideal situation to use implicit remoting because I can provide access to custom functions in a single place, without needing to distribute custom modules and scripts. I can update these commands in a single place. They can be used as if they were local, but I don’t have to worry about staff using an old version of a script.

It’s important to note that PowerShell Remoting is security neutral. My Help Desk now has access to connect to my server; however, they cannot do anything that they couldn’t already do. If they don’t have rights to delete user accounts, I couldn’t provide them access to the Remove-ADUser cmdlet and expect them to have the capability to remove user accounts. Permission-denied errors will still occur, just as if they were using the Active Directory Users and Computer MMC snap-in.

The concept of constrained endpoints is used to great effect with Microsoft Office 365 and hosted Exchange Server. I have the ability to connect to a common endpoint, which exposes only the commands available for me to manage my mailboxes. This gives me the capability to automate my hosted Exchange Server environment, even though it’s completely off my network.

Image of command output

Remoting is truly the killer feature of Windows PowerShell. It’s incredibly useful now, and it has lots of future potential. The WSMan framework is a secure and reliable foundation for Microsoft and non-Microsoft software developers, and hardware manufacturers to build their management tools. Remoting can be used to create solutions today, and it will only get more impressive with the release of Windows PowerShell 3.0 in Windows 8 and Windows Server 2012.

Additional Resources

Administrator’s Guide to Windows PowerShell Remoting

Layman’s Guide to PowerShell 2.0 Remoting

Secrets of PowerShell Remoting

~Jason

Thank you, Jason, for an awesome series on remoting. Join us tomorrow for guest blogger, Will Steele.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hi Jason,

    this is another awesome part of your PS remoting series!

    I didn't knew about creating endpoints at all and it is surely something our admins should consider,

    if they are going to open Powershell for our users!

    You have published a deep-dive-series on Powershell Remoting here wihich is a great point to start at

    when we'll discuss the security and management aspects of rolling out Powershell.

    Thanks a lot!

    Klaus.

  • Jason,

    This is a great introduction series! Thanks for sharing.

    I've made a TechNet Wiki article linking to your series as I feel it is important to try to generate more exposure to your practical insights and technical know-how regarding PowerShell Remoting.

    social.technet.microsoft.com/.../12661.an-introduction-to-powershell-remoting-hey-scripting-guy-five-part-blog-series.aspx

    Cheers,

    Craig

  • @Klaus There are certainly many applications for constrained endpoints. There are also some nice improvements coming in PowerShell 3.0 that add functionality and make the process easier. Definitely check out the Secrets of PowerShell Remoting eBook, as it has a chapter specifically addressing security concerns.

    @Craig Awesome! Thanks for taking the time to create a wiki article. I appreciate it.

  • Hello Guru of Scripts,

    I am in need of a script by I can scan my 500 windows server (win2k3, win2k8 ) to generate installed physical RAM on the server and pagefile size for all the servers , pagefiles for all the drives (C: D: Y: Z: etc ).

    Could help me with some link or blog or help on this?
    All your help highly appreciated.


    Thanks
    Dhirendra