Transparent sessions

This feature requires HCP Boundary or Boundary Enterprise

Beta feature

Beta functionality is stable, but possibly incomplete and subject to change. We strongly discourage using beta features in production deployments of Boundary.

Transparent sessions shift Boundary from an active connection model to a passive connection model. Boundary operates in the background instead of requiring you to remember specific resource IDs or ephemeral ports to connect to targets. As long as Boundary authenticates a user and the user is authorized to access the target, Boundary intercepts the DNS call and routes traffic through a session automatically.

Transparent sessions require aliases and the Boundary Client Agent.

The Boundary Desktop client facilitates quick target discovery and session establishment using your preferred client. If you configure aliases for your targets, install the Boundary Client Agent, and ensure you are authenticated to the cluster, connections are transparent to the user. Boundary provides OS notifications to make it clear when you connect to a target using a transparent session.

Boundary supports Windows and MacOS for the transparent sessions public beta.

Requirements

Before you configure transparent sessions, you must:

Ensure that the Boundary CLI and Boundary Desktop are not installed in the environment in which you want to run the transparent sessions beta.
Download the appropriate Boundary installer for your Windows or MacOS environment from the releases page.

Install clients

Complete the following steps to install the Boundary Client Agent, CLI, and Desktop client:

Install Boundary using the installer. Make sure to select the options Boundary Client Agent, CLI, and Desktop.
Open the CLI and type the following command to confirm that the version is 0.18.0:
```
$ boundary version
```
In the CLI, run the status command to confirm that the Boundary Client Agent has started:
```
$ boundary client-agent status
```

Configure targets

The following section details how to configure targets and test the transparent sessions public beta feature.

If you use a cluster that was created earlier than release 0.16.0, you must add the grant list-resolvable-aliases so that the client agent can populate the local alias cache. As an example, you could add the grant type=user;actions=list-resolvable-aliases;ids=*.

Complete the following steps to configure targets and test transparent sessions:

Authenticate to Boundary using the CLI or Desktop client.
Create a new target with an alias or create an alias for an existing target. Ensure that you have authorization to establish a session to the target.
Open the client of your choice and connect to your target using the alias.
Boundary routes your session using the Boundary Client Agent. You can validate that Boundary routed the session by looking at the Sessions page in the Desktop client, by typing boundary sessions list -recursive in the CLI, or by looking at sessions managed by the Client Agent using boundary client-agent sessions.
Note
The Client Agent periodically requests an updated list of aliases from the controller, so the alias may not work immediately after you create it. It should not take longer than 2 minutes for the alias to be updated in the Client Agent. If you still see connection issues after 2 minutes, follow the troubleshooting steps in the Client Agent troubleshooting guide.

When you have validated that transparent sessions work, you can create and establish transparent sessions to other services. Make a list of the services you use, add these resources to Boundary as targets, and create workers as needed for network partitions.

Known issues

Refer to the following table for known issues that may affect the public beta:

Issue	Description
Connection is reset when trying to reconnect	If you use an SSH transparent session and then cancel the connection, you may have trouble reconnecting until Boundary cleans up the session.
SSH connection fails with man-in-the-middle warning	On Ubuntu systems, the initial transparent session may be successful, but any subsequent connections prompt a warning that you may be experiencing a man-in-the-middle attack.
Boundary Client Agent authentication does not persist across restarts	When you reboot, you are required to re-authenticate to the Client Agent before you can use transparent sessions.
Windows shortcuts are mandatory	The Windows installer always installs Desktop and Start menu shortcuts. This is a known issue. Shortcuts will be optional in a future version of the installer.
Windows installer prompts for restart	When you install Boundary, the Windows installer occasionally prompts you to restart your computer, however it is not necessary.
Boundary Client Agent resumes on reboot	If the Client Agent is paused and the machine is rebooted, the Client Agent will be resumed after the reboot.
Single-word aliases do not work on Windows	If you create an alias consisting of a single word without a dot (`.`), the alias will not work on Windows.
Windows installer does not support partial installations	The Windows installer fails to start the Client Agent if the Desktop client is not installed at the same time.
Alias connection failures inside containers/VMs	Using transparent sessions rely on network access to the local network of the computer the Client Agent is running on. Network enclaves such as those created by Docker containers and VMs cannot reach this network.

More information

Refer to the following topics for more information: