Connecting to Your Targets

A user's guide on connecting to your targets

Use the tiles below to jump to your desired target connection guide.

Linux Servers

Databases

Kubernetes Clusters

Windows RDP and SQL Servers

Web Servers

SSH Tunnels and File Copy

Most connections to secured targets begin with a zli connect, with the exception being SSH tunnels. In many cases, this will follow the format zli connect {target-name}. If the target has only one target role associated with it, BastionZero will assume that target role and try to establish a connection. If there are multiple target users for a single target, then the zli will prompt you to connect with the explicit user role. This will look like zli connect {user}@{target-name}.

To verify user roles or target names, run zli lt -d before your connect command.

Linux Servers

Start a shell session with your remote host using the zli.

zli connect {target-name}

For example, if the remote host is named centos, connecting looks like zli connect centos.

BastionZero supports connecting to your remote Linux hosts using your IdP username as the target user. For example, if the email you use to authenticate with BastionZero is [e-mail], then connecting to your target looks like zli connect examplename@centos. For more information on how to set up your target connect policies to support this, navigate to our policy management page.

Databases

If you're looking for guidance on connecting to a passwordless database, take a look at our how-to guides here.

Begin your connection to your database using the zli.

zli connect {database target name}

For example, if the database target name is postgres, connecting looks like zli connect postgres.

The zli will return a local port number that can be used in your database client to connect. For example, if using psql, the command would be psql -U {username} -h localhost -p {port number}, where the port number was returned in the output of the zli connection command.

Kubernetes Clusters

Connect to your Kubernetes cluster using the zli.

zli connect {user}@{clusterName}

Substitute {user} and {clusterName} with the Kube user and cluster name you have configured in policy.

After running zli connect, the zli updates your default kubeconfig file located at ~/.kube/config with an additional, BastionZero-managed context entry: bzero-{user}@{clusterName}. This context entry provides access to your cluster through BastionZero. The zli also sets your current-context to this newly created entry, so that you can use your Kubernetes tools immediately without having to switch your context.

The zli respects the KUBECONFIG environment variable. Set KUBECONFIG to a different filepath before running zli connect if you would like a different kubeconfig to be updated rather than the default one.

Verify your current-context has been updated.

$ kubectl config current-context
bzero-{user}@{clusterName}

Once your current-context is set, you can use kubectl or other Kubernetes tools (e.g. Lens) to access your cluster.

Additionally, the zli can forward your commands to kubectl if you use zli kube -- {your kubectl command}. The benefit of using the zli kube command is that it captures human-readable commands in the BastionZero logs (i.e. get pods) whereas direct kubectl commands will appear only as API calls.

The zli permits you to connect to multiple Kubernetes clusters at once, or the same cluster multiple times as long as the {user} is distinct from any existing connections to the same target you've made on your machine. Each new Kubernetes connection results in an additional context entry following the same bzero- format mentioned above. If you ever forget the context name for your current Kubernetes connections, run zli ld kube to display a list of your Kube connections and their corresponding context name.

Switch between different cluster connections by using kubectl config use-context {contextName}, or a third-party tool such as kubectx. kubectl config get-contexts -o name will display all contexts by name.

Recommendation: Install fzf as well as kubectx, so that you can use an interactive, fuzzy-finder menu to switch between your contexts. See kubectx's documentation here for more information.

To see all of your open Kubernetes connections (or if you've forgotten the cluster name or Kube role configured) across all of your machines where you've connected via the zli, run zli lc -t kube:

$ zli lc -t kube
┌──────┬──────────────────────────────────────┬─────────────┬────────────────┬───────────────────┐
│ Type │ Connection ID                        │ Target User │ Target         │ Time Created      │
├──────┼──────────────────────────────────────┼─────────────┼────────────────┼───────────────────┤
│ Kube │ 947f3990-4219-4148-85be-233802d976ba │ dev-user    │ my-cluster-1   │ 11/17/22, 1:29 PM │
├──────┼──────────────────────────────────────┼─────────────┼────────────────┼───────────────────┤
│ Kube │ fde9997d-780f-49a3-bef3-b1b26d1251cf │ test-user   │ my-cluster-1   │ 11/17/22, 1:30 PM │
├──────┼──────────────────────────────────────┼─────────────┼────────────────┼───────────────────┤
│ Kube │ 3a0be20a-f7c3-4c39-88a8-9c908d957805 │ dev-user    │ othercluster   │ 11/17/22, 1:50 PM │
└──────┴──────────────────────────────────────┴─────────────┴────────────────┴───────────────────┘

Optional: Install kube-ps1

kube-ps1 is a third-party tool that adds your current-context and namespace configured in your kubeconfig file to your Bash/Zsh prompt.

(⎈|bzero-developer@my-cluster:default) $ 

This is a helpful tool because BastionZero's context names include both the {role} and {clusterName} for all your connections to your Kubernetes targets. Since kube-ps1 adds your current-context to your terminal prompt, you'll always know which cluster and role you are currently connected as before issuing a kubectl command.

Windows RDP and SQL Servers

To connect to your Windows RDP or SQL Server targets from the zli, use the following command:

zli connect {windows-target-name}

This command will return a target string, which is a localhost address containing a specific port number (i.e., Started RDP daemon at localhost:64271 for rdp-target1). This is where your RDP or SQL Server connection is being hosted.

For Windows users, connecting to an RDP or SQL Server target automatically launches an appropriate desktop application to facilitate the connection (i.e., Microsoft Remote Desktop or SQL Server Management Studio). This default behavior can be disabled with zli configure set noAppStart true.

For those on Linux or Mac, you can interact with your RDP and SQL Server target using the tool of your choice.

Example of using the target string to interact with an RDP connection with Microsoft Remote Desktop

Once you add your connection, enter your username and password credentials as you normally would.

Web Servers

Connect to your web server using the zli.

zli connect {web-server-name}

For example, if the web server target name is grafana, connecting looks like zli connect grafana.

Your default browser will launch a new tab or window with the connection to your web server.

SSH Tunnels and File Copy

Tunnel to a remote host using the zli

If you have not configured your local machine to connect via tunnel, update your SSH configuration before connecting. This can be accomplished in two ways:

Method 1: Use BastionZero's SSH config management capability.

Use BastionZero to find a list of targets to which you have tunnel or scp access and automatically include them in your SSH config file with the following command:

zli generate sshConfig

Running this command will also provide the following context in your bzero-bz-config file to help you navigate:

#********************************************************************************
#
# BastionZero auto-generated SSH configuration file
#
# This file is auto-generated based on your SSH policy as specified by the
# administrator(s) of your BastionZero account.
#
# All SSH connections are secured through the BastionZero ZLI, ensuring you are secured
# with our MrZAP (multi-roots of trust) protocol.
#
# This file includes the following:
#
# If you have a target access / shell policy, you may use SSH
# to any host within that policy by using the format:
#
# ssh targetUser@bzero-targetHostname
#
# This will proxy the SSH connection through BastionZero as the 'bzero-' wildcard will
# match the proxy entry below.
#
# BastionZero makes specific use of the %n and %s in our configuration statements
# below. %n will pass and proxy the host name as the entry exists. %s will convert it to
# lowercase. Please be cautious if changing these values.
#
# Users
# -----
# If your administrator has provided SSH access with more than one target user, the
# full list has been provided in a comment under the host. To set a default simply
# add the appropriate user line by copying and modifying the line. For example:
#
# # User postgres, centos, user1, ec2-user
#
# Becomes:
#
# # User postgres, centos, user1, ec2-user
# User ec2-user
#
# Target Names
# ------------
# Each host name is formatted in two ways: 
# 1. <target name> and
# 2. <target name>.<environment name>
# This allows you to connect based on environment name for targets that 
# may share the same name.
#
#********************************************************************************

Now, you can connect to any of the listed hosts using native SSH. You may need to specify a user if you have multiple users defined by policy (i.e., ssh root@my-target). Use the directions in the context above to do so.

BastionZero supports connecting to your remote Linux hosts via ssh using your IdP username as the target user. For example, if the email you use to authenticate with BastionZero is [e-mail], then connecting to your target via ssh looks like ssh examplename@centos. For more information on how to set up your target connect policies to support this, navigate to our policy management page.

Method 2: Manually update your SSH config with the output of zli generate ssh-proxy to proxy your SSH connections through BastionZero.

Run the following and copy the output into your SSH config file.

zli generate ssh-proxy

The output will look something like the following:

Host bzero-*
IdentityFile /Users/alice/Library/Preferences/bastionzero-zli-nodejs/bzero-temp-key
ProxyCommand zli ssh-proxy  -s %n %r %p /Users/alice/Library/Preferences/bastionzero-zli-nodejs/bzero-temp-key

Once you've added this to your SSH config file, connect to any remote host using native ssh by appending bzero- to the beginning of the hostname.

Examples

• To SSH as root to the target centos, this will look like ssh root@centos (if you used method 1) or ssh root@bzero-centos (if you used method 2).

• Tunneling to a remote server application may look like ssh -L 6100:127.0.0.1:5432 root@bzero-postgres.

• Tunneling using a client browser to reach an HTTP application on your local network may look like ssh -L 8080:10.0.0.1:80 root@bzero-httpRedirectServer.

Disambiguating between SSH targets

If your organization has SSH targets that share the same name and are in the same environment, you will need to connect to your target using its target ID and prepending the bzero- prefix to ensure the connection routes through BastionZero.

Target IDs can be found by using the following command: zli lt -i.

Once you've found the target ID, to connect, your command may look like:

• ssh root@bzero-0009f4e0-3ab8-4cde-8935-0ad50ccc8dce

Copying files with SCP / SFTP

Because scp and sftp are both built on top of SSH connections, you can use either command to perform file upload/download operations on any remote host for which you have a Tunnel or File Transfer policy. For example, if you followed method 1 above to configure SSH, you could upload a file to the remote machine's home directory with scp file-to-upload.txt centos:~.

When copying files, your data is secured using the same cryptographic protocol that underpins all BastionZero connections.

Note that File Transfer access to a target can only be used to perform uploads and downloads. If you don't have Tunnel access to the same target, you will not be able to execute remote commands, acquire a login shell, or set up port forwarding.

For additional information on SSH, scp, and sftp with BastionZero, check out its ZLI Reference Manual entry.