Register-PSSessionConfiguration

Exploring Register-PSSessionConfiguration in PowerShell

Welcome back to Wahmans PowerShell Blog! Today, we’re diving into a powerful cmdlet in the PowerShell Remoting world: Register-PSSessionConfiguration. This cmdlet allows you to create and register a new session configuration that defines how users can connect to your PowerShell endpoint. It plays a pivotal role in customizing remote Windows PowerShell sessions.

Let’s take a closer look at how to use this cmdlet with four practical examples that grow in complexity—from beginner-friendly to more advanced use cases.

What Is Register-PSSessionConfiguration?

According to Microsoft documentation: "Register-PSSessionConfiguration creates and registers a new session configuration." In practice, this means that you can control what happens when users connect to your machine remotely via PowerShell. This includes controlling access, defining available commands, setting up custom roles, and more.

Example 1: Register a Simple Session Configuration

This is a basic usage scenario where you create a session configuration named SimpleConfig that users can connect to:

Register-PSSessionConfiguration -Name "SimpleConfig"

This will create a new remoting endpoint accessible via Enter-PSSession -ConfigurationName SimpleConfig.

Example 2: Register a Session Configuration with a Custom Startup Script

You can specify a script to run every time a user connects to the session:

Register-PSSessionConfiguration -Name "CustomStartup" -StartupScript "C:\Scripts\Startup.ps1"

This is useful for setting environment variables, loading modules, or doing any necessary prep work.

Example 3: Register a Session with Restricted Language Mode

To increase security, you might want to limit what PowerShell commands are available within the remote session:

Register-PSSessionConfiguration -Name "RestrictedSession" -LanguageMode NoLanguage

This sets the session to NoLanguage mode, which disables invocation of script blocks or expressions. It’s useful for kiosk-like environments or sessions where only predefined commands are permitted.

Example 4: Register a Session for a Specific Group with Role-Based Access

A more advanced example involves creating a session that only members of a particular group can access:

Register-PSSessionConfiguration -Name "AdminOnly" -RunAsCredential (Get-Credential) -SecurityDescriptorSddl 'O:BAG:BAD:(A;;GA;;;S-1-5-21-1234567890-123456789-1234567890-512)'

In this case, the SecurityDescriptorSddl limits access to a specific user group (e.g., Domain Admins), and the session runs under a specific account retrieved with Get-Credential.

Cleaning Up

If you want to remove a session configuration, you can use:

Unregister-PSSessionConfiguration -Name "CustomStartup"

This will deregister the configuration and remove it from the list of available remoting endpoints.

Conclusion

Register-PSSessionConfiguration is a powerful tool for customizing and controlling PowerShell remoting on your systems. Whether you’re just starting out or implementing complex role-based setups, this cmdlet gives you the flexibility and security needed for enterprise environments.

Happy scripting, and I will see you in the next post!