Introduction to PowerShell Endpoints

Summary: Learn about Windows PowerShell endpoints and how they relate to remoting.

 Hey, Scripting Guy! I keep hearing about Windows PowerShell endpoints and constrained endpoints related to remote management. Can you tell me more about these?

—KP

 Hello, KP. Honorary Scripting Guy, Boe Prox, here today filling in for my good friend, The Scripting Guy. Here's a bit about me:

Boe Prox is a Microsoft MVP in Windows PowerShell and a senior Windows system administrator. He has worked in the IT field since 2003, and he supports a variety of different platforms. He is a contributing author in PowerShell Deep Dives with chapters about WSUS and TCP communication. He is a moderator on the Hey, Scripting Guy! forum, and he has been a judge for the Scripting Games since 2010. He recently presented talks on the topic of WSUS and PowerShell at the Mississippi PowerShell User Group. He is an Honorary Scripting Guy, and he has submitted a number of posts as a guest blogger, which discuss a variety of topics. To read more, see these Hey, Scripting Guy! Blog posts.

Boe’s blog: Learn Powershell |Achieve More
CodePlex projects: PoshWSUS, PoshPAIG, PoshChat, and PoshEventUI

This is the first part in a series of five posts about Remoting Endpoints. The series includes:

1. Introduction to PowerShell Endpoints
2. Build Constrained PowerShell Endpoint Using Startup Script
3. Build Constrained PowerShell Endpoint Using Configuration File
4. Use Delegated Administration and Proxy Functions
5. Build a Tool that Uses Constrained PowerShell Endpoint

When performing a variety of tasks, system administrators can leverage Windows PowerShell remoting to connect to remote systems and run commands as though they were logged directly into the server. Remoting has been available since Windows PowerShell 2.0, which means that it goes as far back as Windows Server 2003. Prior to Windows Server 2012, you had to manually enable PSRemoting to provide the necessary configuration to grant access to each server. In Windows Server 2012, Windows PowerShell remoting is already enabled and ready to go.

Administrators do nothing more than connect to a remote session or issue commands from a single workstation against multiple remote systems (known as “fan-out”), and they leverage Windows PowerShell Remoting to accomplish this.

When connecting to a Windows PowerShell endpoint or using Invoke-Command, you are connecting to a remote session configuration (an endpoint) where, depending on the configuration of the endpoint, you have a certain level of access to that remote system. I am going to take you through what an endpoint is, show various properties, and provide examples of a couple different types of endpoints that show how they affect the session.

An endpoint is a set of configurations on a computer that help customize the environment when a user connects to the endpoint from a remote computer. Sessions that offer fewer cmdlets, functions, and other language features that you normally see when using Windows PowerShell are called constrained endpoints. This means that the sessions are tightened up to prevent unauthorized use of commands that could potentially cause harm, or to prevent commands from being run accidently. These can be used to provide a means to run certain commands by a junior system administrator or a service desk.

Following is an example of connecting to a remote system and running a couple of commands:

PS C:\> Enter-PSSession -ComputerName DC1

[DC1]: PS C:\> $env:Computername

[DC1]: PS C:\> Get-Process | Sort WS -Descending | Select -First 5

[DC1]: PS C:\> Exit-PSSession

Starting with Windows PowerShell 3.0, there are typically the following built-in endpoints:

• microsoft.powershell (standard endpoint)
• microsoft.powershell32 (optional if running a 64-bit operating system)
• microsoft.powershell.workflow
• microsoft.windows.servermanagerworkflows

You can see all of your available endpoints by running Get-PSSessionConfiguration.

Note You must run this command as an Administrator. You can only run this locally and not in a remote session (you will get an Access Denied error).

PS C:\> Get-PSSessionConfiguration

In its current default list view, we can see the names of each of the configuration session settings in addition to seeing if the session uses a startup script, and what version of Windows PowerShell will be used with the session. Also note the Permission property. This shows who has access to the remote session. In Windows PowerShell 4.0, Remote Management Users was added as a group for session configuration access.

My example of remoting into a server did not specify a session configuration name, but it did use Microsoft.powershell by default. Let’s take a closer look at this configuration to see some of the settings and take a look at what they mean.

PS C:\> Get-PSSessionConfiguration -Name microsoft.powershell | Select *

Beyond what we have already seen with the default list view of the configuration sessions, we can also see a couple of other settings that are worth noting:

• SecurityDescriptorSddl
  This is the Security Descriptor Description Language (sddl), which is the non-human readable representation of the Permission property. If you are planning to script session configurations, this is where you would go to apply the proper permissions for the configuration.
• URI
  This is the Uniform Resource Identifier (URI) that you can connect to on the remote system.
•  RunAsUser and RunAsPassword
  These are used to provide delegated administration. More about this will be discussed in the coming days.

I mentioned earlier about constrained sessions, which are typically custom created. We can see what those look like in the same way. A custom session configuration resides in a configuration file (.pssc), which resides on the remote server.

PS C:\> Get-PSSessionConfiguration -Name ExampleSession | Select *

Many of the same properties that were in the built-in endpoints are here in the custom endpoint. One is the location of the .pssc file that the session configuration references. Other points of metadata include CompanyName, Description, and Copyright.

Different from the built-in configuration is the Language property, which dictates the language features that are available to the user when they are in the remote session. In this case, FullLanguage is available, which is what you see in a typical Windows PowerShell console session. Other options that are available for LanguageMode are:

Permits all Windows cmdlets and all Windows PowerShell language elements, but it limits permitted types.

Users can run commands (cmdlets, functions, CIM commands, and workflows), but they are not permitted to use script blocks. Only the following proxy functions are available to use: Get-Command, Get-FormatData, Select-Object, Get-Help, Measure-Object, Exit-PSSession, Out-Default.

You can find more information about Windows PowerShell languages in the TechNet Library at about _Language_Modes.

In the end, when you connect to a constrained endpoint, you will see that certain features are not allowed. For instance, let’s say that I am given two cmdlets to use (besides the proxy functions required for the remote session), and I have no access to any .NET types:

PS C:\> Enter-PSSession -ComputerName 'boe-pc' -ConfigurationName ExampleSession

[boe-pc]: PS>Get-WmiObject -Class Win32_Service

[boe-pc]: PS>[datetime]'03/01/2014'

[boe-pc]: PS>Get-Command

KP, tomorrow I will talk about how to use a startup script to configure a constrained endpoint much like what I have just shown. Remoting Endpoint Week will continue tomorrow when I will talk about writing a startup script for a constrained endpoint.

I invite you to follow the Scripting Guys 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.

Boe Prox, Honorary Scripting Guy