End-users of Boundary can utilize the Desktop app to connect to a running Boundary server to easily:

  • Browse available targets
  • Connect to targets
  • Manage active sessions

Security administrators use the Boundary CLI and API to automate infrastructure access management, but the Desktop app makes Boundary accessible to low-code and no-code users. Users that establish sessions with targets frequently will also find the browse, connect, and manage functionality convenient for day-to-day operations.

In this tutorial, you will install the Boundary Desktop app, start Boundary in dev mode and connect to a target.

Prerequisites

  1. A MacOS, Windows, or Linux Workstation
  2. Boundary is still running in dev mode

Install Boundary Desktop

Boundary Desktop can be installed on MacOS, Windows, or Linux systems. Select the tab for your preferred OS.

MacOSWindowsLinux

Boundary Desktop on MacOS can be installed by either:

  • The Homebrew package manager
  • Direct Download

HomebrewDirect Download

Homebrew is a free and open-source package management system for Mac OS X. Install from the official Boundary Desktop cask from the terminal.

To install with Homebrew:

  1. $ brew install hashicorp-boundary-desktop
  1. $ brew install hashicorp-boundary-desktop

Start a dev environment

Boundary Desktop connects with a running instance of a Boundary controller. In non-dev environments, Boundary Desktop would connect to this running controller without hosting it locally.

In this tutorial, you will run a Boundary controller locally using dev mode.

You already have a Boundary instance running in dev mode. If not, start it again.

  1. $ boundary dev
  3. ==> Boundary server configuration:
  5.         [Controller] AEAD Key Bytes: NtnnXhfyf3kWat2bn/dI/mCqQOEsEWY2r6M42G1pJtc=
  6.           [Recovery] AEAD Key Bytes: CppomgVQTvwwONTcLHuxnCPmGxm3S2I53a3h/o8AjJw=
  7.        [Worker-Auth] AEAD Key Bytes: otkRTWVA9nQI4ix31JmQHT+0iecsnSGqkoyPduASjW4=
  8.                [Recovery] AEAD Type: aes-gcm
  9.                    [Root] AEAD Type: aes-gcm
  10.             [Worker-Auth] AEAD Type: aes-gcm
  11.                                 Cgo: disabled
  12.      Controller Public Cluster Addr: 127.0.0.1:9201
  13.              Dev Database Container: nice_ishizaka
  14.                    Dev Database Url: postgres://postgres:password@localhost:55000/boundary?sslmode=disable
  15.          Generated Admin Login Name: admin
  16.            Generated Admin Password: password
  17.            Generated Auth Method Id: ampw_1234567890
  18.           Generated Host Catalog Id: hcst_1234567890
  19.                   Generated Host Id: hst_1234567890
  20.               Generated Host Set Id: hsst_1234567890
  21.              Generated Org Scope Id: o_1234567890
  22.          Generated Project Scope Id: p_1234567890
  23.                 Generated Target Id: ttcp_1234567890
  24.   Generated Unprivileged Login Name: user
  25.     Generated Unprivileged Password: password
  26.                          Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api")
  27.                          Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster")
  28.                          Listener 3: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")
  29.                           Log Level: info
  30.                               Mlock: supported: false, enabled: false
  31.                             Version: Boundary v0.1.8
  32.                         Version Sha: c0f33f982c87c0eb4127cb16cf06b03a37b91dbd
  33.            Worker Public Proxy Addr: 127.0.0.1:9202
  35. ==> Boundary server started! Log data will stream in below:
  37. T13:59:18.863-0600 [INFO]  worker: connected to controller: address=127.0.0.1:9201
  38. T13:59:18.877-0600 [INFO]  controller: worker successfully authed: name=dev-worker
  1. $ boundary dev
  2. ==> Boundary server configuration:
  3.         [Controller] AEAD Key Bytes: NtnnXhfyf3kWat2bn/dI/mCqQOEsEWY2r6M42G1pJtc=          [Recovery] AEAD Key Bytes: CppomgVQTvwwONTcLHuxnCPmGxm3S2I53a3h/o8AjJw=       [Worker-Auth] AEAD Key Bytes: otkRTWVA9nQI4ix31JmQHT+0iecsnSGqkoyPduASjW4=               [Recovery] AEAD Type: aes-gcm                   [Root] AEAD Type: aes-gcm            [Worker-Auth] AEAD Type: aes-gcm                                Cgo: disabled     Controller Public Cluster Addr: 127.0.0.1:9201             Dev Database Container: nice_ishizaka                   Dev Database Url: postgres://postgres:password@localhost:55000/boundary?sslmode=disable         Generated Admin Login Name: admin           Generated Admin Password: password           Generated Auth Method Id: ampw_1234567890          Generated Host Catalog Id: hcst_1234567890                  Generated Host Id: hst_1234567890              Generated Host Set Id: hsst_1234567890             Generated Org Scope Id: o_1234567890         Generated Project Scope Id: p_1234567890                Generated Target Id: ttcp_1234567890  Generated Unprivileged Login Name: user    Generated Unprivileged Password: password                         Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api")                         Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster")                         Listener 3: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")                          Log Level: info                              Mlock: supported: false, enabled: false                            Version: Boundary v0.1.8                        Version Sha: c0f33f982c87c0eb4127cb16cf06b03a37b91dbd           Worker Public Proxy Addr: 127.0.0.1:9202
  4. ==> Boundary server started! Log data will stream in below:
  5. T13:59:18.863-0600 [INFO]  worker: connected to controller: address=127.0.0.1:9201T13:59:18.877-0600 [INFO]  controller: worker successfully authed: name=dev-worker

Recall that Boundary starts in dev mode with default authentication credentials and a set of pre-defined resources.

These admin credentials enable you to log into the Boundary console.

  • Generated Auth Method Login Name: admin
  • Generated Auth Method Password: password

The default login name and password can be overwritten with -login-name and -password flags (e.g. boundary dev -login-name="dev-admin" -password="p@ssw0rd").

If you have any trouble getting dev mode to start properly, refer back to the Start a Development Environment tutorial and then come back here.

Authenticate with Boundary Desktop

Next you will launch the Boundary Desktop app and connect it to the running controller.

  1. Open the Boundary Desktop app installed earlier.

    You will be prompted for the Boundary server origin, which is the URL for the client to connect to the controller via the Boundary API. Running in dev mode, this will be http://localhost:9200

    Boundary Desktop URI

  2. Select the global scope. In non-dev environments you would select the scope you have been provided access credentials for.

  3. Enter admin in the Username field.

    This is the Generated Auth Method Login Name.

  4. Enter password in the Password field.

    This is the Generated Auth Method Password.

  5. Click Authenticate.

    Boundary Desktop Login

    You are presented with the Targets view, which contains the Generated target with the ID ttcp_1234567890. This is the default target enabled by dev mode on your localhost.

    Initial Targets

Connect to a target

Next you will connect to the default target using the Desktop app.

  1. Establish a connection

    Click on Connect next to the default target.

    Connect to Target

  2. Copy the target’s connection details

    You will be presented with a dialog box that displays the target’s connection info. You can copy the connection details to your clipboard by clicking the button to the right of the Local proxy address.

  3. View the pending connection

    Click OK, and navigate to the Sessions view using the sidebar on the left. Notice that the status for the Generated target has been updated to pending.

    Pending Target Connection

  4. Start an SSH session

    Open a new shell session or your SSH client of choice to establish an SSH connection using the copied target details. Be sure to update the port value with the value copied from the connection info. Enter your local administrator password when prompted to connect to the localhost target.

    1. $ ssh -p 55315 127.0.0.1
    2. The authenticity of host '[127.0.0.1]:55315 ([127.0.0.1]:55315)' can't be established.
    3. ECDSA key fingerprint is SHA256:ZsbEADHGE95YlTkqSoKH+OMLHh//u33yEWs6DuB1DSc.
    4. Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
    5. Warning: Permanently added '[127.0.0.1]:55315' (ECDSA) to the list of known hosts.
    6. Password:
    7. Last login: Wed Mar 17 15:06:03
    8. $
    1. $ ssh -p 55315 127.0.0.1The authenticity of host '[127.0.0.1]:55315 ([127.0.0.1]:55315)' can't be established.ECDSA key fingerprint is SHA256:ZsbEADHGE95YlTkqSoKH+OMLHh//u33yEWs6DuB1DSc.Are you sure you want to continue connecting (yes/no/[fingerprint])? yesWarning: Permanently added '[127.0.0.1]:55315' (ECDSA) to the list of known hosts.Password:Last login: Wed Mar 17 15:06:03$

    Issues connecting or disconnects right after entering your password could be due to SSH restrictions on your local machine. Using System Preferences in MacOS, click Sharing, ensure that Remote Login is enabled, and check the Allow access for section to make sure that your user has the correct permissions to log in.

    Once connected, the Sessions view in the Boundary Desktop app should show the Generated target’s status has been updated to active.

    Pending Target Connection

  5. Terminate the connection

    You can close the active session directly from the Boundary Desktop app.

    Under the Sessions view, click Cancel to the right of the status for the Generated target. The status will update to canceling and a confirmation dialog should appear to verify the successful session termination.

    Pending Target Connection

    Back in your terminal session, there should be a dialog confirming a closed connection by the remote host.

    1. $ Connection to 127.0.0.1 closed by remote host.
    2. Connection to 127.0.0.1 closed.
    1. $ Connection to 127.0.0.1 closed by remote host.Connection to 127.0.0.1 closed.

  6. Clean up

    Shutdown the dev environment by navigating back to the terminal session used to run boundary dev, and enter the ctrl+c keystroke to shutdown the dev server.

    1. ^C==> Boundary dev environment shutdown triggered
    2. T13:45:14.835-0600 [INFO]  worker: status ticking shutting down
    3. T13:45:14.836-0600 [INFO]  controller: recovery nonce ticking shutting down
    4. T13:45:14.836-0600 [INFO]  controller: terminating completed sessions ticking shutting down
    5. T13:45:14.836-0600 [INFO]  controller: status ticking shutting down
    6. $
    1. ^C==> Boundary dev environment shutdown triggeredT13:45:14.835-0600 [INFO]  worker: status ticking shutting downT13:45:14.836-0600 [INFO]  controller: recovery nonce ticking shutting downT13:45:14.836-0600 [INFO]  controller: terminating completed sessions ticking shutting downT13:45:14.836-0600 [INFO]  controller: status ticking shutting down$

Next steps

You installed the Boundary Desktop app, connected to a running controller and viewed and managed an SSH session using the app. The Desktop app is typically used for session management, while the Admin console is used for administrative tasks like defining and managing Users, Groups, Roles, Projects and Host Catalogs.

The next step is to configure and manage targets that your organization wishes to protect. The recommended approach is to use Terraform to codify the Boundary configuration.