On this page

PowerShell Sessions and Session Configuration Guide

Updated on June 18, 2026

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

PowerShell PSSessions provide a persistent remote environment that maintains state across multiple commands, enabling sophisticated multi-step administrative workflows. Session configurations—also known as endpoints—define the environment, permissions, and available commands for these sessions. By combining PSSessions with custom session configuration files, administrators can create tailored, secure, and scalable remote management solutions without writing complex C# code.


Understanding PowerShell Sessions​

A PowerShell session, or PSSession, is a persistent connection to a local or remote computer that maintains state across multiple commands. Unlike one-off remote executions that create temporary connections and tear them down immediately, a PSSession remains active until explicitly closed.

When you run a remote command using -ComputerName without a session, PowerShell establishes a temporary connection, executes the command, returns the results, and destroys the remote environment. This is efficient for simple tasks but does not preserve any state. A PSSession, created with New-PSSession, behaves differently:

Conceptually, a PSSession is similar to opening a remote PowerShell console and leaving it open for repeated use.


Creating and Using PSSessions​

Creating a Session​

The New-PSSession cmdlet establishes a persistent connection to a remote computer:


$session = New-PSSession -ComputerName "SERVER01"

This command creates a session object stored in the $session variable. You can create sessions on multiple computers simultaneously by passing an array:


$sessions = New-PSSession -ComputerName "SERVER01", "SERVER02", "SERVER03"

Running Commands Inside a Session​

Use Invoke-Command with the -Session parameter to execute commands within an existing session:


Invoke-Command -Session $session -ScriptBlock {

    Get-Date

    Get-Service -Name "Spooler"

}

The script block executes inside the remote session. Any subsequent command using the same session runs in the same environment, with access to previously set variables and loaded modules.

Entering a Session Interactively​

For interactive administration, use Enter-PSSession:


Enter-PSSession -Session $session

Your prompt changes to reflect the remote machine:


[SERVER01]: PS C:\>

Every command you run now executes on the remote system until you exit:


Exit-PSSession

Closing a Session​

Always close sessions when they are no longer needed to free resources on both local and remote machines:


Remove-PSSession -Session $session

To remove all active sessions:


Get-PSSession | Remove-PSSession

Why Persistent Sessions Matter​

Persistent sessions are essential when you need to:

For example, if you import a module inside a PSSession, it remains available for subsequent commands:


Invoke-Command -Session $session -ScriptBlock {

    Import-Module ActiveDirectory

}



# Later command—module is still available

Invoke-Command -Session $session -ScriptBlock {

    Get-ADUser -Identity "jsmith"

}

Code explanation: The first command imports the Active Directory module into the remote session. The second command uses the same session to run Get-ADUser. The module remains loaded because the session persists between commands.

Without a persistent session, you would need to import the module with every command, adding unnecessary overhead.


Session Configuration: Controlling What Users Can Do​

PowerShell includes a powerful mechanism called session configuration, which defines the environment and permissions available inside a remote session. Session configurations determine:

Every PowerShell session uses a session configuration, also known as an endpoint. When users create a session, they can select a specific configuration or use the default configuration that is registered when PowerShell remoting is enabled.

Session configurations are the foundation of Just Enough Administration (JEA). Even outside JEA, they provide fine-grained control over remote access.

Default Session Configurations​

PowerShell includes several default session configurations:

Each endpoint defines what the remote session allows.


Viewing Available Session Configurations​

Use Get-PSSessionConfiguration to list all registered session configurations on the local computer:


Get-PSSessionConfiguration

This displays each configuration with its name, PowerShell version, startup script, and permission settings.

To view detailed properties of a specific configuration:


Get-PSSessionConfiguration -Name "Microsoft.PowerShell" | Format-List -Property *

Code explanation: The first command retrieves all registered session configurations. The second command retrieves a specific configuration and formats all its properties as a list. This is useful for inspecting the exact settings of an endpoint.

Starting in PowerShell 3.0, the session configuration object returned by Get-PSSessionConfiguration includes additional properties that make it easier to examine and compare configurations.


Creating Custom Session Configurations​

Administrators can create custom endpoints to restrict or tailor remote access. There are two primary methods:

  1. Using a session configuration file (recommended for most scenarios).
  2. Using a C# assembly that defines a custom runspace.

Session Configuration Files​

A session configuration file is a text file with a .pssc extension that contains a hash table of session configuration properties and values. Session configuration files make it easy to create custom session configurations without complex C# assemblies or scripts.

The easiest way to create a session configuration file is by using the New-PSSessionConfigurationFile cmdlet:


New-PSSessionConfigurationFile -Path "C:\Config\LimitedAdmin.pssc"

This command creates a file with default values. All parameters except -Path are optional. If you omit a parameter, the corresponding key in the session configuration file is commented out.

Code explanation: The New-PSSessionConfigurationFile cmdlet generates a human-readable text file containing a hash table of session configuration properties. The file uses the correct syntax and format, and automatically verifies many property values.

Key Session Configuration File Parameters​

The New-PSSessionConfigurationFile cmdlet accepts numerous parameters to control the session environment:

ParameterPurpose-PathSpecifies the file path (required)-AuthorSets the author of the configuration-DescriptionProvides a description of the configuration-SessionTypeDefines the session type (Empty, Default, or RestrictedRemoteServer)-LanguageModeControls language features (FullLanguage, RestrictedLanguage, NoLanguage, or ConstrainedLanguage)-ExecutionPolicySets the script execution policy-PowerShellVersionSpecifies the PowerShell version for the session-ModulesToImportLists modules to import automatically-VisibleCmdletsLimits visible cmdlets to a specific list-VisibleFunctionsLimits visible functions to a specific list-VisibleAliasesLimits visible aliases to a specific list-VisibleExternalCommandsLimits visible external commands-VisibleProvidersLimits visible providers-RunAsVirtualAccountRuns the session under a virtual account-TranscriptDirectorySpecifies where to store session transcripts

For detailed descriptions of all properties, refer to the New-PSSessionConfigurationFile help topic.

Example: Creating a Restricted Session Configuration​

The following example creates a session configuration file that restricts users to a limited set of cmdlets:


New-PSSessionConfigurationFile -Path "C:\Config\HelpDesk.pssc" `

    -Author "IT Department" `

    -Description "Restricted session for help desk staff" `

    -LanguageMode RestrictedLanguage `

    -VisibleCmdlets "Get-Service", "Restart-Service", "Get-Process", "Get-EventLog" `

    -VisibleFunctions "Get-DiskSpace" `

    -ModulesToImport "Microsoft.PowerShell.Utility"

Code explanation: This configuration restricts the language mode to RestrictedLanguage, which prevents users from using script blocks and other advanced language features. Only the specified cmdlets, functions, and modules are available. This creates a locked-down environment suitable for help desk staff who need to perform specific tasks.


Registering a Session Configuration​

After creating a session configuration file, register it as an endpoint using Register-PSSessionConfiguration:


Register-PSSessionConfiguration -Name "HelpDesk" -Path "C:\Config\HelpDesk.pssc" -Force

The -Name parameter specifies the endpoint name that users will reference when connecting. The -Path parameter points to the session configuration file.

Code explanation: This command registers a new session configuration named "HelpDesk" using the settings defined in the HelpDesk.pssc file. The -Force parameter suppresses confirmation prompts.

Users can then connect to this endpoint:


Enter-PSSession -ComputerName SERVER01 -ConfigurationName "HelpDesk"

Or with Invoke-Command:


Invoke-Command -ComputerName SERVER01 -ConfigurationName "HelpDesk" -ScriptBlock {

    Get-Service -Name "Spooler"

}

Important Registration Considerations​


Modifying Existing Session Configurations​

Use Set-PSSessionConfiguration to change the properties of an existing session configuration:


Set-PSSessionConfiguration -Name "HelpDesk" -Path "C:\Config\HelpDesk_Updated.pssc" -Force

To change individual properties without replacing the entire configuration file, use the appropriate parameters:


Set-PSSessionConfiguration -Name "HelpDesk" -VisibleCmdlets "Get-Service", "Restart-Service", "Stop-Service"

Code explanation: The first command replaces the HelpDesk configuration with the settings from a new file. The second command updates only the VisibleCmdlets property while keeping other settings intact.

To remove a property value and revert to the default, pass an empty string ("") or $null:


Set-PSSessionConfiguration -Name "HelpDesk" -StartupScript ""

Using Sessions with Invoke-Command on Multiple Targets​

Invoke-Command can operate on multiple sessions simultaneously:


$s1 = New-PSSession -ComputerName "SERVER01"

$s2 = New-PSSession -ComputerName "SERVER02"



Invoke-Command -Session $s1, $s2 -ScriptBlock {

    Get-Service -Name "Spooler"

} | Select-Object PSComputerName, Name, Status

Code explanation: This creates two persistent sessions, runs the same command on both, and returns results with the PSComputerName property indicating the source machine. This approach is more efficient than repeatedly creating and destroying temporary connections.


Role-Based Access Control with Session Configurations​

Session configuration files support role-based access control through the -RoleDefinitions parameter. This allows you to give different users different capabilities in the same session based on group membership.

To use role definitions, first create role capability files using New-PSRoleCapabilityFile:


New-PSRoleCapabilityFile -Path "C:\Config\HelpDeskRole.psrc" -VisibleCmdlets "Get-Service", "Restart-Service"

Then reference these role definitions in your session configuration file:


$roleDefinitions = @{

    "CONTOSO\HelpDeskGroup" = @{

        RoleCapabilities = "HelpDeskRole"

    }

    "CONTOSO\SeniorAdmins" = @{

        RoleCapabilities = "FullAccessRole"

    }

}



New-PSSessionConfigurationFile -Path "C:\Config\RoleBased.pssc" -RoleDefinitions $roleDefinitions

Code explanation: The -RoleDefinitions parameter accepts a hashtable where keys are group names and values specify the role capabilities available to members of that group. This enables the same endpoint to provide different levels of access based on who is connecting.


Session Options and Advanced Configuration​

For advanced scenarios, use New-PSSessionOption to create a session option object that controls various session behaviors:


$option = New-PSSessionOption -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block

New-PSSession -ComputerName "SERVER01" -SessionOption $option

Code explanation: This creates a session option object with an idle timeout of two hours (7200000 milliseconds), no operation timeout, and output buffering set to Block mode. The session option is then applied when creating a new PSSession.

Common session options include:


Summary​

PowerShell sessions provide a persistent, stateful remote environment that enables sophisticated administrative workflows. Session configuration allows administrators to define exactly what users can do inside those sessions, from full administrative access to tightly restricted, task-specific environments.

Key takeaways:

Together, PSSessions and session configurations form the backbone of secure, scalable remote management in PowerShell. They are essential for modern Windows administration and form the basis for advanced remoting scenarios such as Just Enough Administration (JEA).

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Invoke-Command

Next

Security Considerations