- Pip install Boto3 - Thu, Mar 24 2022
- Install Boto3 (AWS SDK for Python) in Visual Studio Code (VS Code) on Windows - Wed, Feb 23 2022
- Automatically mount an NVMe EBS volume in an EC2 Linux instance using fstab - Mon, Feb 21 2022
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
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
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
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
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.
