PowerShell Remoting doesn’t require administrator privileges. To allow non-administrators to perform specific administrator tasks, you can work with constrained session configurations (endpoints).

In my last post, I explained how you can give non-administrators access to PowerShell Remoting. If these users have to perform specific tasks that require administrator rights, you don’t have to promote them to administrators. With the help of restricted endpoints, you can precisely define what a user can and cannot do with PowerShell.

In the context of Web services, an endpoint is the “point” where the methods that are exposed to the client are defined. PowerShell Remoting is, of course, a Web service. Therefore, in the context of PowerShell, an endpoint simply is a session configuration. Thus, session configurations enable you to define what language features are available to the user.

Three session configurations are available by default on a 64-bit Windows machine: microsoft.powershell, microsoft.powershell.workflow, and microsoft.powershell32. On an elevated PowerShell console, you can list all available session configurations with Get-PSSessionConfiguration:

PS C:\> Get-PSSessionConfiguration

The default session configurations

The default session configurations

When you start a PowerShell session (local or remote), you usually work with the microsoft.powershell session configuration. You can change the default configuration with the Set-PSSessionConfiguration cmdlet. However, in my view, it is better to create a new endpoint if you intend to work with your own configuration. This ensures that an administrator always has full access to the computer if required.

With the help of Register-PSSessionConfiguration, you can register a new session configuration:

Register-PSSessionConfiguration -Name myEndpoint

If you now run Get-PSSessionConfiguration again, you will see that another endpoint has been added. In the next example, we limit the amount of data that a user can send to the machine with a single command to 10MB (the default is 50MB):

Set-PSSessionConfiguration -Name myEndpoint -MaximumReceivedDataSizePerCommandMB 10

To use the new endpoint, you simply have to create a new session and specify the name of the session configuration:

$mySession = New-PSSession -ConfigurationName myEndpoint

It is also possible to create a remote session with a session configuration:

$mySession = New-PSSession -ComputerName $RemoteComputer -ConfigurationName myEndpoint

You can now run commands with Invoke-Command in this session or enter an interactive session:

Invoke-Command –Session $mySession –ScriptBlock {Get-Process}
Enter-PSSession -Session $mySession

The restriction of the session is fairly simple. To work with more sophisticated constrained endpoints, you will usually have to create a session configuration file:

New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc

This command creates a new file named GetSessions.pssc (you can use any name with the extension pssc) in your current folder. This is an easy-to-read text file that you can modify with any text editor. However, it is usually better to use the New-PSSessionConfigurationFile cmdlet because it prevents syntax errors.

An easy-to-read session configuration file

An easy-to-read session configuration file

You can then use the session configuration file to register a new endpoint:

Register-PSSessionConfiguration -Name GetSessions -Path .\GetSessions.pssc -Force

In our example, we constrained the session to all cmdlets that begin with the Get verb. A user who works in such a session therefore won’t be able to modify objects on the computer.

On a second computer, you could try the restriction with the following commands:

$GetSession = New-PSSession -ConfigurationName GetSessions
Invoke-Command -Session $GetSession {Get-Process}

The $RemoteComputer variable would contain the name of the machine where we registered the session configuration. If you now try a cmdlet that begins with another verb, you will receive an error message telling you that the term is not recognized as the name of a cmdlet:

Invoke-Command -Session $GetSession {Get-Process | Select-Object Name}

Note that you can’t even establish an interactive session with this session configuration:

Enter-PSSession -Session $GetSession

You will receive the error message: Enter-PSSession : The term 'Measure-Object' is not recognized as the name of a cmdlet, function, script file, or operable program.

A constrained endpoint without the support of interactive sessions

A constrained endpoint without the support of interactive sessions

The reason is that interactive sessions require the availability of a couple of cmdlets that are invisible in our sample session. I will say more about this in a follow-up post.

When you register a new endpoint, the session configuration file is copied to C:\Windows\System32\WindowsPowerShell\v1.0\SessionConfig with a file name in the format: EndpointName_GUID.pssc. The GUID is just a unique identifier that you can also find in the configuration file.

Note that the registered session configuration will be permanent. That is, if you reboot the computer, the corresponding endpoint will still be available. If you want to remove the endpoint, you have to unregister the session configuration:

Unregister-PSSessionConfiguration -Name GetSessions -Force

In the examples in this post, I assumed that an administrator uses the endpoint. As I outlined in my previous post, you can allow standard users to work with remote sessions. This also works for your own session configurations. You can assign a security descriptor when you register the session or you can change it afterward with Set-PSSessionConfiguration:

Set-PSSessionConfiguration -Name GetSessions -ShowSecurityDescriptorUI -Force

Assigning a new security descriptor to an endpoint

Assigning a new security descriptor to an endpoint

If those users require administrator privileges for a specific task, you can register the session configuration with credentials that have the required privileges:

Register-PSSessionConfiguration -Name myEndpoint -Path .\myEndpoint.pssc   -RunAsCredential myDomain\administrator -Force

PowerShell will then prompt you to enter the administer password and store it in the endpoint. In this example, a standard user would have full admin privileges on the corresponding machine without having to know the administrator password. Of course, you would then restrict the features of the endpoint so that the standard user can’t damage the system.

By default, PowerShell offers its full repertoire of cmdlets and language elements to a user. To expose only a restricted set of features, you basically have three major options: you can work with session types, use language modes, or restrict the visible cmdlets. I already mentioned the last option today. In my next post, I will describe these three methods in detail.


Leave a reply

Please enclose code in pre tags

Your email address will not be published.


© 4sysops 2006 - 2023


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account