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 proxy Server Port, available on the SSH Proxy Configuration page or RDP 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, you may include the MFA token in the connection string. Otherwise, the 12Port Proxy Server will prompt for MFA enforcement.

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.

Interactive MFA Session Prompts

When MFA credentials are not included in the connection string, and the user is required to complete MFA validation for session initiation, the Proxy Server will prompt the user with the appropriate MFA provider validation.

This section provides examples of interactive MFA prompts generated by the Proxy Server, along with the expected user actions during authentication. MFA prompts occur after the user authenticates to the Proxy Server.

TOTP
Enter the valid TOTP (Time-Based One-Time Password) code from the authentication application on the authorized device and press Enter to validate.

Duo Security
- Enter the Duo Security Passcode from the Duo Mobile App on the authorized device and press Enter, or
- Leave the prompt blank and press Enter to send a Push notification to the registered device.

YubiKey
Use the authorized YubiKey (hardware or software key) to automatically populate the prompt with the generated code.
- The Proxy Server will typically submit the Enter command automatically.
- If the automatic submission does not occur within a few seconds, manually press Enter to complete submission.

Entra ID
- Enter the OTP (One-Time Password) code from the Microsoft Authenticator app on the authorized device and press Enter, or
- Leave the prompt blank and press Enter to send a Push notification.
- If Number Matching is required, enter the number displayed in the Proxy Server prompt within the Authenticator app to complete MFA validation.

Example: Number Matching prompt

Mail MFA
Enter the valid MFA code received in the user's Email inbox and press Enter to validate.

Note

To receive Mail MFA codes:
- The 12Port user must have a valid Email Address assigned to their account.
- The 12Port Tenant must have an enabled and working SMTP integration to send the email.

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.

SAML Credentials

If the user that authenticates into 12Port is an account from an externally integrated SAML provider, then this user must authorize the use of their credentials in the 12Port web portal's Account page. To perform this operation:

Login to this tenant's 12Port web portal with the SAML credentials.
Navigate to My Profile > Account page and for the Transit Credentials parameter, click the Update Transit Credentials button on the right side of the field.
In the Transit Credential prompt, enter the valid Password for this SAML account and click the Ok button.

Once the password has been confirmed, this user may now authenticate with their native client to the 12Port proxy server using their SAML credentials.

username@tenant.com#assetID@host -p proxyport

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

Note

If the SAML credential's password is updated in the future, this user must perform these steps again to re-authorize 12Port with the new password.

RDP File Download

The RDP File Download option is available on the View Assets page for assets that support the RDP protocol. This option generates and downloads an .rdp configuration file that can be used by native desktop RDP clients to connect through the 12Port RDP Proxy.

The generated file includes pre-populated values for:

The 12Port destination host
The Asset ID
The 12Port user

Additional RDP configuration parameters (beyond the destination host, user, and asset ID) are defined in the editable template located at Configuration > Templates > rdp-file.

The destination hostname included in the generated .rdp file is derived from the 12Port address configured in the parameter Integration > SMTP > Tenant URL. If this value is not set, the system falls back to using the 12Port host name. In many cases, this fallback may be undesirable, e.g., using 12port.contoso.com when that hostname is not intended to represent a specific tenant environment.

SSH Proxy Public Key Authentication

Public key authentication is supported for native SSH client access to the 12Port SSH Proxy, providing a secure alternative to password-based login.

By using a private key stored locally, this method eliminates the need to transmit passwords over the network, reducing the risk of interception. It also enables stronger access control by allowing only users with the corresponding private key to authenticate. In addition to improved security, public key authentication supports automation and scripting, making it easier to manage remote systems, and can enhance user convenience, especially when keys are protected with a passphrase.

To enable public key authentication with the SSH Proxy using a native SSH client, follow the steps below:

Generate an SSH Key Pair
Generate a new SSH private and public key pair just as you would for accessing Unix, Linux, or other network devices. As an example, you could use the following command to create a 4096-bit RSA key pair (you may optionally specify a passphrase to protect the private key):
```
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```
This example command will create two files in the ~/.ssh directory of your user account:
- id_rsa - your private key (keep this secure)
- id_rsa.pub - your public key
Upload the Public Key to the SSH Proxy
Upload your Public Key file (i.e., id_rsa.pub) to the SSH Proxy's My Profile > Authorized Keys page in the 12Port web portal. This step is required to allow the SSH Proxy to recognize and authenticate your key.
- Login to the 12Port tenant web portal, navigate to My Profile > Authorized Keys and click Add.
- Enter a Description.
- In the Key field, click the Upload button and select your Public Key file.
- Toggle on the Enabled switch.
- Click Save.

Note

Public/private key pairs for SSH proxy authentication are unique to each user and to each tenant. Only this user themselves, can login to the 12Port tenant and upload their public key to their profile.

3. Connect Using Your Private Key
Once your public key is uploaded, connect to the SSH Proxy using your private key with a command like the following:

ssh -i ~/.ssh/id_rsa user@12port.contoso.com

Replace user with your 12Port username and 12port.contoso.com with the actual hostname or IP address of the SSH Proxy.

For additional details on key pair generation, management, and usage, consult the documentation of your native SSH client.

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 optionally included)

RDP Proxy session using the native Windows Remote Desktop client (interactive TOTP prompt via the 12Port Proxy Server when not included in the connection string)

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.