Configure transparent sessions

This feature requires HCP Boundary or Boundary Enterprise

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 transparent sessions.

Requirements

Before you configure transparent sessions, you must:

Ensure that any previous versions of the Boundary Desktop or CLI client in your local environment are fully uninstalled before you install the Boundary clients using the latest Boundary installer.
Download the appropriate Boundary installer for your Windows or MacOS environment from the Install Boundary page or the releases page.
Install the Boundary Client Agent, CLI, and Desktop client.
- Refer to Install the Boundary clients for instructions.
- Refer to the transparent sessions interoperability matrix for a list of third-party products that have been tested for use with the Boundary installer and Client Agent.

You should also make sure you have the appropriate grants configured so that you can resolve aliases and establish transparent sessions. For more information, refer to the Grants section in the Client Agent documentation.

Warning

A known issue regarding how grants were previously created in HCP Boundary may cause you to receive a 500 error when you attempt to list resolvable aliases. Clusters created before April 26, 2025 may be missing the following grants:

ids={{.User.Id}};type=user;actions=list-resolvable-aliases

ids=*;type=target;actions=list,read

If your cluster is missing these grants, HashiCorp recommends adding them.

For more information, refer to the known issue.

Configure targets

The following section details how to configure targets to use transparent sessions.

Tip

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=*.

For more information, refer to the Grants section in the Client Agent documentation.

Complete the following steps to configure targets:

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.
RDP targets require a custom port for transparent sessions. Refer to RDP targets for two possible ways to configure custom ports.

RDP targets

Due to a port conflict with the Windows Remote Desktop Connection app on modern Windows operating systems (Windows 11+, Windows Server 2025), transparent sessions fail when you use the default port (3389) to establish an RDP connection. The port conflict is an issue even if you enable Remote Desktop. This issue prevents users from establishing transparent sessions by entering a target alias in their RDP client.

To connect to an RDP target using a transparent session from a Windows client, you must use a custom port. Two primary workarounds are available:

Configure a default client port: Set a custom port (e.g., 83389) in the target's configuration within Boundary. The user must then connect by specifying this port in their RDP client (for example, my-server:83389). You can specify a default client port when you create target aliases.
Use .rdp bookmark files: Create and distribute an .rdp file that contains the full connection string, including the custom port for the localhost listener (for example, full address:s:localhost:51129). Bookmark files allow users to connect by simply opening the file.

When users connect to the RDP target using transparent sessions, they must specify the custom port with the alias in the RDP client, for example:

my.alias.name:83389

Next steps

Open the client of your choice and connect to your target using the alias.

More information

Refer to Troubleshoot issues with the Client Agent for a list of known issues involving transparent sessions.