Restricting the rights of PowerShell users with a constrained session configuration

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

Michael Pietroforte

Michael Pietroforte is the founder and editor of 4sysops. He is a Microsoft Most Valuable Professional (MVP) with more than 30 years of experience in IT management and system administration.
Profile gravatar of Michael Pietroforte

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:

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:

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):

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

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

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

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:

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:

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:

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:

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

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:

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:

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:

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.

Take part in our competition and win $100!

0 Comments

Leave a reply

Your email address will not be published. Required fields are marked *

*

CONTACT US

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

Sending
© 4sysops 2006 - 2017
Do NOT follow this link or you will be banned from the site!

Log in with your credentials

or    

Forgot your details?

Create Account