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.
Ensure that both IPv4 and IPv6 protocols are enabled for your environment. The Client Agent requires both protocols to start and perform DNS lookups.

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.

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.