Native Client Remote Sessions

A Native Client Remote Session is an RDP or SSH session that is initiated and executed entirely through a locally installed desktop client. Examples include connection tools such as Windows RDP, PuTTY, mRemote, Royal TS, and others. The user authenticates, optionally with MFA, directly to the 12Port Access Server, which then brokers the connection to the managed endpoint in a single seamless step.

Access to a native client remote session is governed by both the assigned Access Profile and the user's permissions on the asset. To successfully initiate a session, the user must have:

At minimum, Asset Role: Viewer permission on the asset; and
An assigned Access Profile that includes either Native Session: Allow or Native Session: Record.

If either condition is missing, the user will be unable to connect to the 12Port proxy server, and the session will not start.

Starting a Native Client Remote Session

To start a native client remote session, you must construct a custom connection string within your preferred desktop client. The required parameters may include:

Username (and domain, if applicable)
Sub-site Name (if not /root)
MFA token (if MFA is enabled)
Asset Name or ID
Proxy port number

The following examples demonstrate how to build these connection strings for different configurations.

Native Client Remote Session Connection Strings

Open your RDP or SSH connection tool and refer to the examples below for proper formatting.

No MFA Required

For connections that do not require MFA, use one of the following formats:

username#assetID@host -p proxyPort

bwilliams#efaecd97-f9d4-4ac4-b35b-b2d71491354d@12port.contoso.com -p 2203

username: Your login to the 12Port web portal
assetID: Unique ID of the target asset
host: Hostname of the 12Port portal (e.g., localhost, 12port.contoso.com)
proxyPort: The 12Port SSH proxy Server Port, available on the SSH Proxy Configuration page.

Alternatively, you can use the asset Name instead of its ID:

Note

We recommend using assetID for maximum reliability, as it uniquely identifies each asset. Relying on asset names can lead to connection failures if multiple assets share the same name.

username#assetName@host -p proxyPort

bwilliams#Prod DB 08@12port.contoso.com -p 2203

recordName: The asset’s display name. Only use recordName if it is unique.
All other variables follow the same definitions as above.

Note: If multiple assets share the same name, the session will fail. Use the assetID instead for an exact match.

MFA Required

If MFA is enabled for this remote session, include the MFA token in the connection string:

username?TOTP#assetID@host -p proxyport

bwilliams?823072#efaecd97-f9d4-4ac4-b35b-b2d71491354d@12port.contoso.com -p 2203

TOTP: Your valid six-digit MFA token
All other variables follow the same definitions as above.

Or, using the asset Name:

Note

We recommend using assetID for maximum reliability, as it uniquely identifies each asset. Relying on asset names can lead to connection failures if multiple assets share the same name.

username?TOTP#assetName@host -p proxyport

bwilliams?782361#Prod DB 08@12port.contoso.com -p 2203

Note: If multiple assets share the same name, the session will fail. Use the assetID instead for an exact match.

Domain Account Logins

If logging in with a domain account, use this format:

username@domain?TOTP#assetID@host -p proxyport

bwilliams@contoso.com?782361#efaecd97-f9d4-4ac4-b35b-b2d71491354d@12port.contoso.com -p 2203

username@domain: Your domain login in this exact format.
All other variables follow the same definitions as above.

Sub-site Assets

If the asset resides in a sub-site (i.e., not under /root), include the site name:

username/siteName?TOTP#assetID@host -p proxyport

bwilliams/DevOps?782361#efaecd97-f9d4-4ac4-b35b-b2d71491354d@12port.contoso.com -p 2203

For domain accounts and sub-sites:

username@domain/siteName?TOTP#assetID@host -p proxyport

bwilliams@contoso.com/DevOps?782361#efaecd97-f9d4-4ac4-b35b-b2d71491354d@12port.contoso.com -p 2203

siteName The name of the sub-site where the asset resides
All other variables follow the same definitions as above.

Native RDP Access Examples

Example Connection Values:

12Port host: 12port.contoso.com
Tenant RDP Proxy Port: 3317
12Port Local Username: qsadmin
AssetID: 28b15a95-cb64-4025-99b6-5fbc2ad99957
TOTP Code: 356194

RDP Proxy session using the native Windows Remote Desktop client

RDP Proxy session using the native Windows Remote Desktop client (TOTP required)

RDP Proxy session using the mRemoteNG client

Native SSH, SCP, and SFTP Access

You can connect to remote systems using native command-line tools such as ssh, scp, and sftp. These commands operate over standard protocols supported by 12Port’s SSH proxy. While this section focuses on CLI-based interactions, tools such as FileZilla and WinSCP, which offer graphical interfaces, are also compatible with the 12Port proxy, provided they adhere to SSH protocol standards.

Although ssh, scp, and sftp may appear similar at a glance, they serve different purposes:

SCP is suited for quick, scriptable file transfers.
SSH exec allows automation tools like Ansible to run commands remotely in a Zero Trust environment.
SFTP is ideal for interactive file browsing and transfers using a terminal or GUI.

Each of these methods supports the same authentication mechanisms as interactive SSH sessions described in the previous section, including MFA, domain accounts, and others.

SCP: Secure Copy Protocol

Uploading a File to a Remote Asset
This example command uploads the local file C:/Users/taskexec/Projects/DataPipeline/etl_script.py to the /home/administrator/datapipeline directory on a remote asset. The asset is identified by its unique asset ID and accessed via the 12Port proxy server 12port.contoso.com on port 2203. Authentication is handled via the 12Port Zero Trust model using the user bwilliams.

scp -P proxyPort -o User='username#assetID' sourceFilePath host:destinationFolderPath

scp -P 2203 -o User='bwilliams#efaecd97-f9d4-4ac4-b35b-b2d71491354d' C:/Users/taskexec/Projects/DataPipeline/etl_script.py 12port.contoso.com:/home/administrator/datapipeline

Example: SCP Upload File using PowerShell SSH Client.

Downloading a File from a Remote Asset
This example command downloads the remote file /home/administrator/etl_script.py from the specified asset and saves it in the designated local directory C:\Users\taskexec\Projects\DataPipeline:

scp -P proxyPort -o User='username#assetID' host:/sourceFilePath destinationFolderPath

scp -P 2203 -o User='bwilliams#efaecd97-f9d4-4ac4-b35b-b2d71491354d' 12port.contoso.com:/home/administrator/etl_script.py C:\Users\taskexec\Projects\DataPipeline

Example: SCP Download File using PowerShell SSH Client.

SSH: Secure Shell

Use SSH exec to run remote commands on a target asset through the 12Port proxy. As an example, the following command lists the contents of the /home/administrator/datapipeline directory on the remote asset:

ssh username#assetID@host -p proxyPort 'command'

ssh bwilliams#efaecd97-f9d4-4ac4-b35b-b2d71491354d@12port.contoso.com -p 2203 'ls -alp /home/administrator/datapipeline'

This method is commonly used for automation tools (e.g., Ansible) or administrative scripting in Zero Trust environments.

Example: SSH exec using PowerShell SSH Client.

SFTP: Secure File Transfer Protocol

This example command initiates an interactive SFTP shell session with the remote asset. Use it to upload, download, and navigate directories.

sftp -oPort=proxyPort username#assetID@host

sftp -oPort=2203 bwilliams#efaecd97-f9d4-4ac4-b35b-b2d71491354d@12port.contoso.com

Once connected, the following basic SFTP commands are available:

?: List available commands
ls: List contents of the remote directory
put : Upload a file to the remote system
get : Download a file from the remote system
exit: Close the SFTP session

Note: The sftp shell commands are standard client-side and server-side features. The 12Port proxy acts only as a secure broker and does not modify or extend these commands.

Example: SFTP file transfer using PowerShell SSH Client.

Example: SFTP file transfer using WinSCP Graphical Client.

Completing a Remote Session

After completing your session, it's strongly recommended to log out, disconnect, or exit the session using the appropriate method on the remote endpoint. Simply closing the client window may leave the session in a disconnected state, which could impact the endpoint or block future connections for other users.

Peer Node Configuration (HTTP Proxy)

In deployments where a Peer Node is used to provide access to isolated network segments, the HTTP Proxy must be enabled on the remote tenant. This setup allows the Main Node to broker remote access connections to target assets through the Peer Node.

This section walks you through configuring the HTTP Proxy on the Peer Node, creating the required service account and API token, and setting up the Peer Node connection from the Main Node.

Step 1: Enable and Configure HTTP Proxy on the Peer Node

Log in to the Peer Node with an Administrator account.
Navigate to Configuration > HTTP Proxy
Make note of the Server Port value. This will be required later during Main Node configuration. Ensure that this port is accessible from the Main Node. If necessary, update the firewall settings on the Peer Node to allow inbound connections on this port.
Set Protocol to HTTP
Toggle on Enabled
Click Save.

Step 2: Create a Service Account and API Token on the Peer Node

Navigate to Management > Users and click Add to create a new Local Directory User account. This user will serve as the service account.
Assign the Service Role to this user:
- Go to Management > Site Roles, click Grant
- In the User field, select the account you just created.
- Toggle on the role Service.
- Click Grant.
Create the API Token:
- Go to Management > API Tokens, click Add
- In the User field, select the account that was just assigned the Service role.
- Set an appropriate Expiration date.
- Leave Filter empty.
- Optionally, add a Description like Proxy Service Token.
- Toggle on Enabled.
Click Save.
After saving:
- Go to Actions > Show Details for the newly created token
- Click Unlock Token in the JWT field, then Copy
- Save this JWT token securely, it will be used when configuring the Main Node

Step 3: Configure the Peer Node on the Main Node

Log in to the Main Node as an Administrator or Configuration Manager.
Navigate to Configuration > Peer Nodes and click Add.
- Enter a unique and recognizable Name for this node.
- Toggle on Includes HTTP Proxy
  - Proxy Host: Enter the hostname of the Peer Node (e.g., 12port.contoso.com).
  - Proxy Port: Enter the Server Port value noted from the Peer Node's HTTP Proxy configuration.
  - Access Token: Paste the JWT API token copied from the Peer Node.
Click Save to complete the Peer Node configuration.

Note

If a Peer Node is already configured for Job Runner and/or Gateway Access, you do not need to create a duplicate. Instead, you can update the existing configuration to include the HTTP Proxy settings.

Once completed, the Main Node can route Proxy-based remote access connections through this Peer Node to isolated assets. Make sure to test the connection and confirm routing functionality through the Session Report.