Skip to content

PowerShell Proxy

The PowerShell Proxy enables secure PowerShell remoting through the platform by brokering connections between a local PowerShell client and remote Windows hosts. Connections are routed through the platform and authenticated using credentials stored in the secure vault, ensuring that privileged credentials are never exposed to end users.

The proxy uses Windows Remote Management (WinRM) and the WSMan protocol to establish remote PowerShell sessions. Users interact with the target system using standard PowerShell remoting commands while the platform transparently handles credential retrieval, authentication, and session brokering.

This architecture allows organizations to maintain centralized credential control while still enabling administrators and automation tools to perform remote management tasks on Windows systems.

Overview

The PowerShell Proxy provides a secure tunnel for PowerShell remoting sessions. Instead of connecting directly to the target host, the user connects through the platform which brokers the session and retrieves credentials from the vault.

PowerShell remoting is built on WinRM, Microsoft's implementation of the WSMan (Web Services for Management) protocol. WinRM provides the transport mechanism that allows remote execution of PowerShell commands and interactive sessions across Windows systems.

Once the proxy session is established:

  1. The user initiates a PowerShell connection from their local workstation.
  2. The connection is routed through the platform's PowerShell Proxy service.
  3. The platform retrieves the required credential from the secure vault.
  4. The proxy authenticates to the target Windows host using WinRM.
  5. A PowerShell session is created and commands are executed on the remote host.

The user interacts with the session as if they were directly connected through standard PowerShell remoting.

Architecture

The PowerShell Proxy relies on standard PowerShell remoting components while introducing an additional proxy layer for security and credential management.

Local PowerShell Client
        │
        │  WinRM / WSMan
        ▼
12Port Authentication Layer
        │
        │  Confirm user identity and authorization
        ▼
12Port Asset Database
        │
        │  Verify user permission and current workflow state;
        │  retrieve asset credentials for injection into the data stream for remote host authentication
        ▼
12Port PowerShell Proxy
        │
        │  WinRM / WSMan
        ▼
Remote Windows Host

Key components include:

Component Description
PowerShell Client Local PowerShell console used by administrators or automation tools
PowerShell Proxy 12Port component that brokers WinRM connections
Auth Layer Validates user identify and authorization into 12Port
Secure Vault Stores privileged credentials used for authentication
Remote Host Windows server configured for PowerShell remoting

The proxy ensures that authentication credentials are never directly exposed to the user.

Use Cases

The PowerShell Proxy makes connecting to remote Windows hosts simple and secure. IT admins can open a session to a server in seconds, run checks, restart services, or manage users, all without exposing sensitive passwords.

For teams managing multiple endpoints across sites, the proxy handles authentication and auditing automatically. You can push updates, review logs, or configure settings without worrying about who has access to credentials.

Developers and support engineers also benefit. Scripts can be tested or system info retrieved directly on the target host, and automation tasks can be run via the PowerShell Proxy without embedding passwords in code. The experience feels just like a normal PowerShell session, but all credentials and access are fully protected.

Privilege Escalation

In environments where privileged access is restricted, the PowerShell Proxy can also be used to perform administrative tasks through controlled privilege escalation. Rather than granting users permanent administrative rights, the platform retrieves the appropriate privileged credentials from the secure vault when the session is established.

This allows administrators to run commands, manage services, or perform system maintenance on remote Windows hosts using elevated privileges while their standard user account remains unchanged. The privileged credentials remain protected within the vault, ensuring that elevated access is temporary, controlled, and fully auditable.

In configurations that use Mirror or Shadow accounts, the proxy automatically resolves and applies the appropriate credential during session establishment. This allows PowerShell remoting sessions to execute with the required privilege level without exposing administrative passwords to the user.

Requirements

Before using the PowerShell Proxy, the following prerequisites must be met.


WinRM Enabled on Target Host

The remote Windows host must have WinRM enabled and running, as PowerShell remoting relies on the WinRM service and the WSMan protocol to receive remote commands.

winrm quickconfig

WinRM must be reachable from the 12Port host server.


PowerShell Remoting Enabled

PowerShell remoting must be enabled on the target system.

Administrators can enable remoting using:

Enable-PSRemoting -Force

This command:

  • Starts the WinRM service
  • Configures the WSMan listener
  • Opens required firewall ports
  • Registers PowerShell session configurations

Enabling remoting ensures that the target host can receive WSMan requests from the PowerShell Proxy.


Network Connectivity

The following connectivity requirements must be satisfied:

  • User's computer must reach the 12Port server over the defined PowerShell Proxy port
  • 12Port host server must reach the remote host over WinRM ports
  • DNS resolution or IP connectivity must exist
  • Remote Host firewall rules must allow inbound WinRM traffic

Configuration

Step 1: Enable the PowerShell Proxy Service

Before using the PowerShell Proxy, the service must be enabled within the tenant configuration.

  1. Log in to the 12Port web portal using a Site Administrator account.
  2. Navigate to Configuration > PowerShell Proxy.
  3. Toggle the Enabled option on.
  4. Note the Server Port value as this will be needed for connection.
  5. Save the configuration.

PowerShell Proxy Enabled

When the service is enabled, the PowerShell Proxy will begin listening for incoming PowerShell remoting connections over the defined Server Port.

Take note of the Server Port value displayed on this configuration page. This port number is required when connecting from a local PowerShell client to the proxy service.

Connections initiated by users will target this port on the 12Port host server, where the proxy will accept the request and broker the remote session using WinRM.


Step 2: Create Vault Asset

Create or configure the credentials used by the PowerShell Proxy in a Windows Host asset:

  1. Navigate to the credential vault.
  2. Create a Windows Host Asset that contains the required values to connect to the remote Host via WinRM (valid Host, User and Password).
    1. Ensure that the credentials supplied have the required permission on the remote Host to connect via WinRM (user must be a member of the local Remote Management Users or Administrators group)
  3. Assign the required Permission and Access Profile to the asset.

12Port retrieves the host and credentials automatically when initiating the PowerShell Proxy sessions.


Step 3: Connect from a Local PowerShell Client

Once the PowerShell Proxy service is enabled, the remote host is configured for WinRM, and the corresponding Asset is created in the vault, users can initiate a remote PowerShell session through the proxy using standard PowerShell remoting commands.

PowerShell supports multiple methods for connecting and providing credentials. The example below demonstrates one common approach using Get-Credential and Enter-PSSession.


Establish Trusted Host (Required for Remote PAM Servers)

If the PowerShell client is connecting to a PAM server other than localhost, the system must trust the remote host before a PowerShell Proxy connection can be established.

Run the following command on the client machine:

Set-Item WSMan:\localhost\Client\TrustedHosts -Value "pam.contoso.com"

Replace pam.contoso.com with the hostname of your PAM server.

This command updates the WSMan trusted hosts list, allowing the PowerShell client to initiate WinRM connections to the proxy server.


Provide Credentials to the Proxy

Credentials used to connect through the PowerShell Proxy, like the other 12Port proxy connections, follow a specific format:

user#assetID or user#assetName (when using assetName, the Name must be unique)

Where:

  • user – PAM user account
  • assetID or assetName – target asset configured in the PAM system (by unique ID or Name) that is used by 12Port to connect to the remote Host.

For example:

bwilliams#28b15a95-cb64-4025-99b6-5fbc2ad99956 or bwilliams#WinProdServer

To collect the credentials interactively, run:

$cred = Get-Credential -User "bwilliams#WinProdServer" -Message "Enter Password"

The prompt will request the password associated with the PAM user account. This credential is then passed to the PowerShell Proxy when establishing the session.


Workflow Access Restrictions

If the target Asset is protected by an access workflow, the user must have an approved access request before a PowerShell Proxy session can be established.

When a connection request is received, 12Port evaluates the user's permissions and any configured access workflow policies associated with the Asset. If the user does not have an active approved request, the session will be denied and the PowerShell connection attempt will fail.

This behavior applies in the following scenarios:

  • The user has not submitted an access request for the Asset.
  • An access request has been submitted but is still pending approval.
  • The request was rejected or has expired.

In these cases, the user must first submit and receive approval for an access request through the tenant's 12Port web portal before attempting to establish the PowerShell Proxy session again.

Once the request is approved and active, the PowerShell Proxy connection can be established using the standard credential format described above.


Start the Remote PowerShell Session

Use Enter-PSSession to open an interactive PowerShell remoting session through the proxy.

Example:

Enter-PSSession -ComputerName "pam.contoso.com" -Port 5990 -Credential $cred

Where:

Parameter Description
ComputerName Hostname of the PAM server running the PowerShell Proxy
Port Server Port displayed in Configuration > PowerShell Proxy
Credential Credential object created using Get-Credential

When the command is executed:

  1. The PowerShell client establishes a WinRM connection to the PAM server.
  2. The 12Port PowerShell Proxy receives the request.
  3. The proxy retrieves the appropriate credential from the secure vault.
  4. The proxy authenticates to the target Windows host using WinRM.
  5. An interactive PowerShell session is established.

From the user's perspective, the session behaves like a normal PowerShell remoting session.


Optional: Connect Without Pre-Creating a Credential Object

You may skip the Get-Credential step and allow PowerShell to prompt for credentials automatically.

Example:

Enter-PSSession -ComputerName "pam.contoso.com" -Port 5990 -Credential (Get-Credential)

When prompted, enter the credential in the format:

user#assetID or user#assetName (when using assetName, the Name must be unique)

PowerShell will then prompt for the corresponding password.

Note

Run PowerShell as an admin to execute this command.


Step 4: Test the Remote Session

After establishing the PowerShell Proxy session, it is recommended to verify that commands are executing on the remote Windows host associated with the vault Asset rather than on the local workstation.

Because the connection is established through the 12Port PowerShell Proxy, the PowerShell prompt may still appear similar to a local session. Running a simple verification command can confirm that the session is executing remotely.


Verify the Remote Hostname

Run the following command inside the PowerShell Proxy session:

hostname

This command returns the hostname of the system where the command is executed.

If the PowerShell Proxy session is working correctly, the returned hostname should match the target remote Host defined in the Asset, not the local workstation from which the PowerShell client was launched.

Example output:

WIN-PROD-SERVER

This confirms that the PowerShell client is successfully connected through the proxy and executing commands on the remote system using remote PowerShell over WinRM.


Optional Verification Commands

Additional commands can also help verify the remote environment:

$env:COMPUTERNAME

or

(Get-CimInstance Win32_ComputerSystem).Name

These commands return the hostname of the system currently executing the PowerShell session.

Example output:

WIN-PROD-SERVER

If the returned value matches the Asset configured in the vault, the WinRM session established through the PowerShell Proxy is functioning correctly.

Audit Events

The following Events report entries are recorded during PowerShell Proxy Start and End sessions.

Event Log Entry (Start Session):
Level: Information
Category: Operation
Event: Create Session
Message: channel=PS, gateway=<peerNode>, account=<assetUser> PowerShell Proxy Create Session Event Report Log Entry

Event Log Entry (End Session):
Level: Information
Category: Operation
Event: Complete Session
Message: channel=PS PowerShell Proxy Create Session Event Report Log Entry

Troubleshooting

If you experience issues connecting to a remote host using the PowerShell Proxy, the following checks can help identify common configuration or connectivity problems. Most connection issues are related to WinRM, WSMan configuration, or network access between the proxy service and the remote Windows host.


Verify WinRM is Enabled on the Target Host

The PowerShell Proxy relies on Windows Remote Management (WinRM) and the WSMan protocol to execute remote PowerShell commands. If WinRM is not enabled on the target Windows host, remote sessions cannot be established.

Log in to the Windows host that will accept PowerShell sessions and run:

Enable-PSRemoting -Force

This command performs several required configuration steps:

  • Starts the WinRM service
  • Creates the WSMan listener
  • Configures firewall rules required for WinRM
  • Registers PowerShell remoting session endpoints


Verify the WSMan Endpoint

After enabling WinRM, verify that the WSMan endpoint is active by running:

Test-WSMan

If the command returns a response containing information about the WinRM service, the WSMan endpoint is functioning correctly.

Example output:

wsmid           : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
ProductVendor   : Microsoft Corporation
ProductVersion  : OS: 0.0.0 SP: 0.0 Stack: 3.0

If no response is returned, WinRM may not be running or may be blocked by firewall rules.


Verify the WinRM Service is Running

Confirm that the WinRM service is running on the remote Windows host:

Get-Service WinRM

Expected output:

Status Name DisplayName ------ ---- ----------- Running WinRM Windows Remote Management

If the service is not running, start it using:

Start-Service WinRM


Verify the WinRM Listener Configuration

The target host must have an active WSMan listener configured to accept WinRM requests.

Check the current listener configuration:

winrm enumerate winrm/config/listener

A properly configured system should display an HTTP or HTTPS listener.

Typical ports include:

Protocol Port
HTTP 5985
HTTPS 5986


Verify Trusted Hosts Configuration

If connecting to a PowerShell Proxy host other than localhost, the PowerShell client may require the remote server to be added to the WSMan TrustedHosts list.

Run the following command on the client machine:

Set-Item WSMan:\localhost\Client\TrustedHosts -Value "pam.contoso.com"

Replace pam.contoso.com with the hostname of your PAM server.

You can verify the current configuration using:

Get-Item WSMan:\localhost\Client\TrustedHosts


Verify PowerShell Proxy Port Configuration

Ensure that the port configured in Configuration > PowerShell Proxy matches the port used in the PowerShell connection command.

Example connection:

Enter-PSSession -ComputerName pam.contoso.com -Port 5990

If the port does not match the configured PowerShell Proxy Server Port, the connection will fail.


Verify Network Connectivity

Confirm that the client machine can reach the PAM server and that the PAM server can reach the remote Windows host.

Basic connectivity can be tested with:

Test-NetConnection pam.contoso.com -Port 5990

Successful output indicates that the PowerShell Proxy service is reachable.


Verify the Session Target

If the session connects but commands appear to run locally, verify the remote host by running:

hostname

or

$env:COMPUTERNAME

The returned hostname should match the target asset configured in the vault, confirming that the PowerShell session is running on the remote host through the WinRM / WSMan proxy connection.


If issues persist after performing these checks, verify that:

  • The target asset is correctly configured in the vault
  • The user assigned to the asset has permission to access the remote host
  • The user assigned to the asset has an Access Profile that allows Native Sessions
  • The WinRM service on the target system allows remote connections from the proxy server