- Courses
- đź’»Programming Languages
- 🪟PowerShell
- PowerShell for System Administration
- Remote Management
- Sessions and Session Configuration
On this page
PowerShell Sessions and Session Configuration Guide
Updated on June 18, 2026
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:
- It creates a persistent remote PowerShell host.
- The host remains active until you explicitly close it.
- Variables, imported modules, and working directories remain available across commands.
- You can enter the session interactively or use it programmatically.
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:
- Run multiple related commands on the same remote machine.
- Load a module once and reuse it across commands.
- Perform multi-step administrative tasks.
- Maintain state, such as variables or temporary files.
- Work with remote systems interactively.
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:
- Which users can create sessions on the computer.
- Which commands, cmdlets, and functions users can run.
- Which language features are allowed (full language, restricted language, or no language).
- Which modules are loaded automatically.
- Whether the session runs as a privileged virtual account.
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:
Microsoft.PowerShell— the default full-language endpoint.Microsoft.PowerShell32— a 32-bit endpoint on 64-bit systems.Microsoft.PowerShell.Workflow— for workflow sessions.
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:
- Using a session configuration file (recommended for most scenarios).
- 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​
- Administrative privileges are required to register session configurations.
- WinRM must be enabled on the local computer.
- Registered configurations are stored in the WS-Management provider under
WSMan:\localhost\Plugin\. - The
-NoServiceRestartparameter prevents the WinRM service from restarting, which can be useful in production environments.
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:
-IdleTimeout: Maximum time the session can remain idle before disconnecting.-OperationTimeout: Maximum time for a command to complete.-OutputBufferingMode: Controls how output is handled when the buffer is full (Block, Drop, or None).-SkipCACheck: Skips certificate authority validation (use with caution).
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:
- PSSessions are persistent connections that maintain state across commands.
- Session configurations (endpoints) define the environment, permissions, and available commands for sessions.
- Session configuration files (
.pssc) make it easy to create custom configurations without complex C# code. - Use
New-PSSessionConfigurationFileto create configuration files. - Use
Register-PSSessionConfigurationto register endpoints. - Use
Set-PSSessionConfigurationto modify existing configurations. - Role definitions enable different access levels based on group membership.
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!
Previous
Invoke-Command
Next
Security Considerations
-
Understanding PowerShell Sessions
-
Creating and Using PSSessions
- Creating a Session
- Running Commands Inside a Session
- Entering a Session Interactively
- Closing a Session
-
Why Persistent Sessions Matter
-
Session Configuration: Controlling What Users Can Do
- Default Session Configurations
-
Viewing Available Session Configurations
-
Creating Custom Session Configurations
- Session Configuration Files
- Key Session Configuration File Parameters
- Example: Creating a Restricted Session Configuration
-
Registering a Session Configuration
- Important Registration Considerations
-
Modifying Existing Session Configurations
-
Using Sessions with Invoke-Command on Multiple Targets
-
Role-Based Access Control with Session Configurations
-
Session Options and Advanced Configuration
-
Summary
