LogoLogo
Main SiteStart Now
  • Home
    • What Is BastionZero?
      • Server Access
      • Database Access
      • Kubernetes Access
      • Web Server Access
    • Product Security
    • Architecture
    • Taxonomy
  • Deployment
    • Getting Started
    • Installing the ZLI
    • Installing the Agent
    • Installing the Desktop App
  • Automation & Integrations
    • CircleCI
    • GitHub Actions
    • Go SDK
    • Google Cloud Run
    • Slack
      • Using the BastionZero app for Slack
    • Terraform
    • Third-Party Clients
  • Admin Guide
    • Authentication
      • SSO Management
      • User Management
      • MFA Management
      • Service Accounts Management
    • Authorization
    • Auditing
    • Target and Connection Management
  • How To Guides
    • Passwordless Database Access
      • Passwordless Access to MySQL and Postgres on GCP Cloud SQL
      • Passwordless Access to AWS RDS PostgreSQL
      • Passwordless Access to AWS RDS MySQL
      • Passwordless Access to Self-Hosted Postgres
    • How to use BastionZero to connect to a Linux Host using the ZLI
    • How to use BastionZero to manage SSH Keys
  • User Guide
    • Installing the ZLI
    • ZLI Cheat Sheet
    • Connecting to Your Targets
    • Troubleshooting Guide
  • ZLI Reference Manual
  • API Specification
  • Getting Help
  • Security Policy
  • Open Source Software Credits
    • Backend Services
    • Bzero Agent
    • Client Daemon
    • Desktop App
    • Go SDK
    • Helm Provider
    • Terraform Provider
    • Web App
    • ZLI
  • Product Changes
  • Service Status
  • GitHub
Powered by GitBook

Copyright © 2024

On this page
  • Step 1: Agent installation
  • Install using ZLI Quickstart
  • Install using Yum
  • Install using Apt
  • Install using Helm
  • Install using YAML
  • Install using Bash
  • Install using Ansible
  • Install for Windows
  • Step 2: Agent Registration
  • Bzero flags
  • Autodiscovery
  • Installation by use case
  • Servers
  • Databases
  • Kubernetes
  • Windows Servers
  • Web Servers
  • Dynamic Access Targets
  • SSH Tunnels & Secure File Copy
  1. Deployment

Installing the Agent

BastionZero's agent, bzero, secures access to your target through MrTAP and centralized policy.

PreviousInstalling the ZLINextInstalling the Desktop App

Last updated 7 months ago

The BastionZero product is maintained for existing BastionZero customers only.

Moving forward, we are natively rebuilding BastionZero’s technology as Cloudflare’s service.

Agent installation has 2 parts:

  1. on your target using one of the methods below.

  2. with BastionZero.

Step 1: Agent installation

BastionZero's agent, bzero, is compatible with x86 and amd64 platforms. It is available through apt and yum package managers, a Bash script, a guided zli Quickstart, Ansible playbook, and via helm and yaml for Kubernetes.

If you'd like to see installation instructions by use case, take a look at our guides .

Install using ZLI Quickstart

Quickstart takes as little as 3 minutes to secure your SSH targets.

It uses your existing SSH config file to identify and secure the hosts you'd like to onboard to BastionZero.

  1. Launch the 4-step Quickstart process. Quickstart will:

    • Ask you to log in to BastionZero. If you haven't created an account yet, you can do so from this step.

    • Select the hosts you want to secure with BastionZero. The available hosts are pulled from your SSH config.

    • Confirm your selection.

    • Install and register the BastionZero agent, bzero, on the chosen SSH target(s).

zli quickstart

Install using Yum

  1. Use the yum-config-manager to add the BastionZero repo.

    sudo yum-config-manager --add-repo https://download-yum.bastionzero.com/bastionzero.repo
  2. Install dependencies on CentOS.

    sudo yum install -y epel-release
  3. Install the bzero agent.

    sudo yum install -y bzero
  4. sudo bzero -registrationKey *registration API key secret*

Registration keys are the only secret needed for use with BastionZero.

Install using Apt

  1. Install the BastionZero public key from the Ubuntu key-server.

    curl -sSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xe5c358e613982017" | gpg --dearmor | sudo tee /usr/share/keyrings/bastionzero.gpg > /dev/null
  2. Add the BastionZero repo with:

    echo "deb [signed-by=/usr/share/keyrings/bastionzero.gpg] https://download-apt.bastionzero.com/production/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/bastionzero.list > /dev/null
  3. Update the apt cache.

    sudo apt update
  4. Install the bzero agent.

    sudo apt install -y bzero
  5. sudo bzero -registrationKey *registration API key secret*

Registration keys are the only secret needed for use with BastionZero.

Install using Helm

  1. Add the BastionZero Helm repo.

    helm repo add bastionzero https://bastionzero.github.io/charts/
  2. helm install bctl-agent bastionzero/bctl-quickstart --set apiKey=$REGISTRATION_SECRET --set clusterName=example-helm-cluster --namespace=bastionzero --create-namespace

Registration keys are the only secret needed for use with BastionZero.

Run helm repo update bastionzero to update to the latest chart version.

Helm installation flags

Flag
Description

apiKey

(required) The secret of your BastionZero registration key.

clusterName

(required) The name your cluster will appear as in BastionZero.

image.agentImageTag

If not specified, latest will be used as the default.

namespace

(optional, but STRONGLY recommended) The namespace you would like to add your cluster into. If omitted, the agent will be installed in the default namespace, which is not recommended.

create-namespace

(optional) If creating a new namespace, this argument must be included as --create-namespace.

replicaCount

(optional) To run multiple BastionZero agents within your cluster, set replicaCount to the total number you would like to host. For example, --set replicaCount=2 indicates you want to run 2 instances of the bzero agent in your cluster.

environmentId

(optional) Environment to put the cluster into. You must specify the ID

agentResources.limits.cpu

(optional) Limits the amount of CPU resources the agent installation can consume.

agentResources.limits.memory

(optional) Limits the amount of memory the agent installation can consume.

agentResources.requests.cpu

(optional) Limits the amount of CPU request resources the agent can consume.

agentResources.requests.memory

(optional) Limits the memory the requests from the agent installation can consume.

quickstartResources.limits.cpu

(optional) Limits the amount of CPU resources the quickstart installation script can consume.

quickstartResources.limits.memory

(optional) Limits the amount of memory the quickstart installation script can consume.

quickstartResources.requests.cpu

(optional) Limits the amount of CPU request resources the quickstart installation script can consume.

quickstartResources.requests.memory

(optional) Limits the memory the requests from the quickstart installation script can consume.

logLevel

(optional) Configure the log level of logs printed by the agent. Valid options include: disabled, trace, debug, info, warn, or error.

Pro tip: To get started faster, consider passing the following parameters to bypass additional policy setup.

Flag
Description

--set "users={SOME_ID_USERS}"

Use a list of comma separated SSO users (i.e., test@test-org.com) to add users automatically to the auto-generated policy. This will allow you and others permission to connect to your cluster right away.

--set "targetUsers={SOME_KUBE_USERS}"

Use a list of comma separated Kube users to automatically add to your policy. We utilize the impersonation API to give permissions to execute commands remotely. In order to create these users, ensure that there is a ClusterRoleBinding or RoleBinding that has a user as a subject. The name of this user is what we'll impersonate.

--set "targetGroups={SOME_KUBE_GROUPS}"

Pass a list of comma separated Kube groups to automatically add to your policy. These groups must already be configured on your cluster.

Best practice with namespaces

The --namespace flag determines which namespace to install the BastionZero agent in. If the namespace already exists, omit the --create-namespace flag.

If you don't use the --namespace flag, then the agent will be installed in the default namespace, which is not recommended.

Best practice with image tag

By default**,** our Helm chart will use the tag latest for the agent. We strongly recommend that you override that using the flag:

--set  "image.agentImageTag=x.x.x"

How to upgrade using Helm

helm repo update
helm upgrade bctl-agent bastionzero/bctl-quickstart --reuse-values -n bastionzero --set "image.agentImageTag=x.x.x"

If image.agentImageTag was not specified during installation, then the agent pod is running with an image of version latest. You can use kubectl rollout to upgrade the agent to the latest version:

helm repo update
kubectl rollout restart deployment bctl-<clusterName>-agent -n bastionzero

where <clusterName> is replaced with the value you specified for clusterName during installation (e.g. example-helm-cluster if using examples above).

The example commands above assume the agent was installed in the bastionzero namespace. Please change accordingly if you installed the agent in a different namespace.

Multi-replica support for the Kubernetes agent using Helm

To take advantage of multiple replica and geo-distributed support for Kubernetes, please ensure that your Helm chart is >= v. 2.3.0.

To improve the redundancy of the Kubernetes agent, the bzero agent supports multiple replicas to prevent connection disruption if a pod is evicted or a cluster is upgraded, etc.

If you are upgrading from an existing installation using Helm, do the following:

helm repo update
helm upgrade bctl-agent bastionzero/bctl-quickstart -n {the namespace bastionzero is installed in} --set replicaCount={number of replicas you want to support} --reuse-values

The above command tells helm to upgrade the bctl-agent using the values from the last installation and to set the replica count to the number of your choosing.

Highly available Kubernetes targets

To create a highly available bzero agent deployment with multiple replicas that exist across cluster availability zones, you must set the topologySpreadConstraints.

To do this, we recommend upgrading your existing targets using the -f <yaml> flag.

First, create a YAML file such as the following:

replicaCount: 2

clusterName: bz-multi-replica-example
apiKey: <registration-api-key-goes-here>

agent:
  deploymentName: bz-agent
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app: bz-agent

Save this YAML file. In the command below, we reference it as multiple-replicas.yaml.

To upgrade your Kubernetes target, you'll need two commands:

helm repo update
helm upgrade bctl-agent bastionzero/bctl-quickstart -n {namespace} -f multiple-replicas.yaml --reuse-values

Security recommendation

When using the --set apiKey flag, the provided BastionZero registration key is stored as an unmasked environment variable in the pod spec. Users with Kubernetes RBAC permission to list pods or deployments can see the contents of this value. In addition, users with RBAC access to view Helm installation history can see this value stored.

Once the secret is created, you can install the agent and set the apiKeyExistingSecret value to the name of the secret instead of using --set apiKey. Please ensure the registration key is stored in secret.data['api-key']. Our Terraform example below shows how to install the agent using the apiKeyExistingSecret flag.

Example Terraform

Below is example Terraform you can use to install the agent via Helm.

terraform {
  required_providers {
    helm = {
      source  = "hashicorp/helm"
      version = "2.9.0"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "2.18.0"
    }
  }
}

provider "helm" {
  kubernetes {
    config_path    = "~/.kube/config"
    config_context = "your-kube-ctx"
  }
}

provider "kubernetes" {
  config_path    = "~/.kube/config"
  config_context = "your-kube-ctx"
}

variable "registration_key" {
  type        = string
  description = "Registration key"
  nullable    = false
  sensitive   = true
}

variable "agent_version" {
  type        = string
  description = "Agent version to install"
  nullable    = false
}

resource "kubernetes_namespace" "bastionzero_namespace" {
  metadata {
    name = "bastionzero"
  }
}

resource "kubernetes_secret" "registration_key_secret" {
  metadata {
    name      = "bctl-agent-registration-key"
    namespace = kubernetes_namespace.bastionzero_namespace.metadata[0].name
  }

  data = {
    "api-key" = var.registration_key
  }
}

resource "helm_release" "bctl_agent" {
  name       = "bctl-agent"
  repository = "https://bastionzero.github.io/charts/"
  chart      = "bctl-quickstart"
  # version = Set this if you want to install a specifc version of the chart.
  # Otherwise, the latest chart is used.

  set {
    name  = "clusterName"
    value = "example-helm-cluster"
  }

  set {
    name  = "apiKeyExistingSecret"
    value = kubernetes_secret.registration_key_secret.metadata[0].name
  }

  set {
    name  = "image.agentImageTag"
    value = var.agent_version
  }

  reuse_values = true

  namespace = kubernetes_namespace.bastionzero_namespace.metadata[0].name
}

Install using YAML

  1. Generate your YAML file, where clusterName is the name of your cluster. This command will generate a Kubernetes YAML with a Service Account, RBAC permissions/bindings, secret, and deployment.

    zli generate kubeYaml {clusterName}
  2. Apply the YAML. Your existing Kubernetes credentials are used to apply the YAML and create BastionZero's agent in the cluster.

    kubectl apply -f {someFile}

Pro tip

To pipe the output to a file directly, use:

zli generate kubeYaml {clusterName} --outputFile {someFile}

where someFile is the name of your YAML file.

Important

This YAML file will only be valid for 10 minutes after creation due to the activation token. If more than 10 minutes has passed, generate the YAML file again.

Install using Bash

You must be a BastionZero administrator to generate the Bash script.

  1. You will see two fields for target name and environment ID, respectively. In the target name field, select one of the four options for how you'd like to name your target: timestamp, DigitalOcean metadata, AWS EC2 metadata, or Bash hostname.

    • For simplicity, we recommend choosing the Default environment.

    • If you'd like to create a new environment, you can do so by using the "Create" -> "Environment" option in the top right corner of the web app.

  2. Click "Try." You should receive a 200 response and an output starting with "autodiscoveryScript." The value of that key is your Bash script.

  3. Use this script in the "User-Data" field when provisioning a new remote host or integrate it with your custom setup.

There is no additional action required to register your agent with BastionZero. It is integrated into the Bash script.

Install using Ansible

You must be a BastionZero administrator to generate the Ansible script.

    • For simplicity, we recommend choosing the Default environment.

    • If you'd like to create a new environment, you can do so by using the "Create" -> "Environment" option in the top right corner of the web app.

  1. Click "Try." You should receive a 200 response and an output starting with "autodiscoveryScript." The value of that key is your Ansible script.

  2. Run this script with your Ansible setup. It will both install and register the bzero agent on your Ansible targets. Note: the BastionZero target names will match the hostnames of the Ansible targets.

There is no additional action required to register your agent with BastionZero. It is integrated into the Ansible script.

Install for Windows

  1. Run Powershell as administrator and create a dedicated directory for the agent and its program files.

    New-Item -ItemType Directory -Force -Path C:\ProgramData\BastionZero
  2. Download the agent.

    Invoke-WebRequest -Uri "https://download-agent.bastionzero.com/release/latest/bin/bzero-agent.exe" -Outfile "C:\ProgramData\BastionZero\bzero-agent.exe"
  3. C:\ProgramData\BastionZero\bzero-agent.exe -registrationKey *registration API key secret*

Registration keys are the only secret needed for use with BastionZero.

Step 2: Agent Registration

For non-administrators to perform agent registration, you must have access to the registration key secret, such as through a vault.

Registration keys are the only secret needed for use with BastionZero.

Flags that can be specified during registration are listed in the table below. Any number of flags can be specified after bzero.

Bzero flags

Important: the -registrationKey flag is required.

Flag
Description

-configureOnly

Updates the agent's configuration and exits. Available on agent version >= 8.2.0.

-environmentId

-keyshards

Linux agent only. (optional) Use for managing split private keys for SplitCert access.

  • get - Print the agent’s keyshard config as a JSON string that can be saved to other agents.

  • clear - Remove all keyshards from this agent. Any SplitCert targets using this agent as a proxy will be inaccessible.

  • addKeys - Add keyshard data from the file returned by a zli generate certificate command when the --agentKey flag was used. Example: bzero keyshards -addKeys path/to/keys.json.

  • addTargets - Add one or more targetIds to this agent’s keyshard config. These targets will be accessible via SplitCert access if they use this agent as a proxy. Example: bzero keyShards -addTargets target1 target2.

  • removeTargets - Remove one or more targetIds from this agent’s keyshard config. These targets will no longer be accessible via SplitCert access from this agent. Example: bzero keyShards -removeTargets target1 target2.

-logLevel

(optional) Sets the log level when running the agent. Allowed values are trace, info, error,. The default is info, the less verbose; trace is very verbose, and error only covers failure cases. You can use this flag in combination with the configureOnly command to change the log level in the agent config. For this new log level to take effect, you will need to restart the agent. Ex: sudo bzero -logLevel trace -configureOnly. This feature is available for agents with version >= 8.2.0.

-orgId

-orgProvider

(optional) Your identity provider, e.g., “Google”, “Microsoft”, “Okta”, etc. If neither the -orgId nor the -orgProvider are set, the information defaults to values provided by BastionZero during the registration process.

-registrationKey

(required) The registration secret provisioned using the web app. It is an API key used only for registering new targets. It is formatted as a base64 string.

-service

Windows agent only. (optional) Allows the agent state to be changed. Options include start, stop, restart, install, and uninstall. We strongly recommend this command is only used if the Windows service manager is unavailable. For example, Stop-Service BastionZeroAgent in Powershell or sc stop BastionZeroAgent in CMD.

-targetName

(optional) The desired name of the target. If no name is provided, this will default to the target’s host name.

-y

(optional) If you’re attempting to register a new version or re-register the same version of the agent on a target that already had an agent installed, use the -y flag to force re-registration and create a new target. The old target will be deactivated. You must to restart the agent using sudo systemctl restart bzero.

Autodiscovery

BastionZero can autodiscover targets without public IPs, open ports, or VPNs. The BastionZero agent, bzero, will initiate an outbound connection to the BastionZero SaaS from any private or public cloud. In some cases, like an application-based firewall, the administrator may need to allow the BastionZero DNS entry or IP, but that is organization-specific. The only requirement for autodiscovery is that the agent can get out to the Internet.

Autodiscovery is initiated by a provisioner. Examples of provisioners may include:

  • Package managers

  • Bash scripts

  • Ansible playbook

  • Helm chart

  • YAML

Installation by use case

Servers

To configure your Linux server, you will need to:

Bash

The Bash script allows installation of the bzero agent through the zli, during instance launch (i.e., by using the "User-Data" with AWS EC2), a Terraform deployment, or other deployment system.

The script contains logic to autodiscover the Linux distribution and microarchitecture (x86 or ARM) in order to download and install the appropriate agent. The script also contains error recovery logic in the event the registration does not succeed for any reason. By default, the script will always download and install the latest BastionZero agent.

Ansible

The playbook contains logic to autodiscover your Linux distribution and microarchitecture (X86 or ARM) in order to download and install the appropriate agent. By default, the playbook will always download and install the latest BastionZero agent.

Databases

To configure your database target using the proxy method, you will need to:

BastionZero relies on a proxy target in order to make a secure connection to your database. The proxy target must be able to resolve a DNS hostname or reach the IP specified by the database target configuration. No configuration, outside of the proxy target having network access to the database, is required.

This feature utilizes our zli for end users to make connections. When connecting to a database target, traffic destined for the database will use local port forwarding through the zli and the proxy target to make a secure MrZAP connection to the database. Upon requesting a connection, the user is returned a local port number, which is used in the database client configuration. The database username, password, and role continue to be managed independent of BastionZero.

Install and Register the BastionZero Agent

Accessing Databases Through a Kubernetes Cluster

Database support is available on the BastionZero agent v.4.0.0+.

Configure Your Database Target

Update the database target fields with the needed context as explained below.

Field
Description

Name

The name of the database target. This is assigned to an environment or used in a policy.

Proxy Target

The name of the backing proxy target. One of proxy target or proxy environment must be set when creating a database target.

Proxy Environment

The name of the backing proxy environment. One of proxy target or proxy environment must be set when creating a database target.

Remote Host

The DNS hostname or the IP address of the database target.

Remote Port

The remote port number that the database target is listening on, usually 443 for HTTPS.

Local Host

The localhost that the BastionZero zli will listen on. This should not need modification.

Local Port

The local port number, which the BastionZero zli will use to intercept traffic. If you leave it blank, an open port on the client machine will be selected for the user.

Environment

The environment to which this target should be added.

A database target’s proxy can now be set to an environment rather than an explicitly named target. When a user connects to the database target, BastionZero will use an available target within the specified environment to proxy the connection. Note that when creating a database target, you will need to specify whether the proxy type is environment or target. This is true both in the web app and through the API.

Add a Database Policy

The database policy will allow a user to connect to the database. For this type of access, BastionZero utilizes a proxy policy. Create a policy using the type proxy and update and save the fields per the descriptions below.

Field
Description

Policy Name

The name of your policy.

Description

Information useful for describing the purpose or context of your policy.

Users

A list of identity provider users who will be authorized to use this policy.

Groups

A list of identity provider groups who will be authorized to use this policy.

Resource Type

Either an envrionment or a list of targets which are the resource(s) authorized for access by this policy.

Kubernetes

To secure a Kubernetes cluster with BastionZero, you'll need to:

Users must have access to the cluster being secured (i.e., are able to create new deployments, secrets, and modify RBAC permissions). It is also recommended that the cluster have existing clusterRoles and clusterRoleBindings.

Verify the Agent Is Running

Once the agent is installed, ensure it has phoned home by listing your targets using

zli list-targets

You should see a list of any existing targets in addition to your newly added Kubernetes cluster, {clusterName}.

You can also check that the agent has been installed using

kubectl get pods -n bastionzero

The output should look similar to the following:

➜  ~ kubectl get pods -n bastionzero
| NAME                                  | READY | STATUS  | RESTARTS | AGE   |
| ------------------------------------- | ----- | ------  | -------- | ---   |
| bzdemo-cluster-agent-7f57c754b9-9qpnq | 1/1   | Running | 0        | 3m12s |

Update Your Kubernetes Policy

Both Helm and YAML agent installation will create an environment and policy for your cluster. It must be updated to grant access to your desired users and target roles.

The auto-created environment and policy take the form "{clusterName}-policy" and "{clusterName}-env" respectively.

  • To update the target users:

    zli policy add-targetuser dev-cluster-policy cluster-admin

    This tells BastionZero that the cluster-admin is an approved Kubernetes user that can access the cluster. Notably, this does not create a Kube policy on the cluster itself for access.

  • To update the target groups:

    zli policy add-targetgroup dev-cluster-policy system:authenticated

    This updates the Kubernetes groups that are allowed to be assumed for this cluster.

  • To update the users:

    zli policy add-user dev-cluster-policy user@domain

    This updates the SSO users allowed to access the cluster.

Ensure the users, roles, and groups are correct by viewing the updated policy.

zli policy list kubernetes

Connect to your cluster via BastionZero

Once the agent has been installed in your cluster and you've configured your Kubernetes policy accordingly, you're ready to connect.

zli connect {role}@{clusterName}

Windows Servers

To configure your Windows server, you will need to:

Follow the guides linked above to install the zli on your client machine and the bzero agent on the Windows server you want to secure access to. Make sure you follow steps 1-3 in the bzero installation guide to complete agent registration with BastionZero.

In this guide, we'll be writing policy against an environment. If you prefer to write policy against explicit targets, you can skip this next step.

Ensure your Windows agent is in the right environment

Author policy for your Windows target(s)

Now that we've confirmed the Windows agent is online and configured, it's time to write policy.

You want to create a "Target Access" policy. Now depending on your use case, you may want to grant users RDP access and/or SQL Server access (if you have an associated SQL Server database you want users to be able to access on your Windows server too).

Continue filling out the remainder of the modal. This will include selecting the IdP users, groups, and/or service accounts you want to have access to your Windows targets. When selecting the "Resource Type," be sure to select "Environments" and the matching environment to your Windows agent. See our example below:

Once you save your policy, you have now set up access to your Windows RDP and SQL Server targets!

Connect to your RDP or SQL Server targets via BastionZero

Connect to your Windows target using:

zli connect {RDP/SQL Server target name}

Web Servers

To configure your web server target, you will need to:

BastionZero relies on a proxy target in order to make a secure connection to your web server. The proxy target must be able to resolve a DNS hostname or reach the IP specified by the web server target configuration. No configuration, outside of the proxy target having network access to the web server, is required.

This feature utilizes the zli for end users to make connections. When connecting to a web server target, the user's default browser will open a new tab with the connection to the web service. This new connection will utilize a local port via a TCP socket to the BastionZero SaaS. This connection is made through the MrZAP protocol. As a result, BastionZero can authenticate and authorize the access, but it cannot alter any commands sent across.

Install and Register the BastionZero Agent

Accessing Web Servers Through a Kubernetes Cluster

Web server support is available on the BastionZero agent v.4.0.0+.

Configure Your Web Server Target

Update the web target fields with the needed context as explained below.

Field
Description

Name

The name of the web target. This is assigned to an environment or used in a policy.

Proxy Target

The name of the backing proxy target. One of proxy target or proxy environment must be set when creating a web target.

Proxy Environment

The name of the backing proxy environment. One of proxy target or proxy environment must be set when creating a web target.

Remote Host

The DNS hostname or the IP address of the webserver target.

Remote Port

The remote port number that the webserver target is listening on, usually 443 for HTTPS.

Local Host

The localhost that the BastionZero zli will listen on. This should not need modification.

Local Port

The local port number, which the BastionZero zli will use to intercept traffic. If you leave it blank, an open port on the client machine will be selected for the user.

Environment

The environment to which this target should be added.

A web target’s proxy can now be set to an environment rather than an explicitly named target. When a user connects to the web target, BastionZero will use an available target within the specified environment to proxy the connection. Note that when creating a web target, you will need to specify whether the proxy type is environment or target. This is true both in the web app and through the API.

Add a Web Server Policy

The web server policy will allow a user to connect to the web server. For this type of access, BastionZero utilizes a proxy policy. Create a policy using the type proxy and update and save the fields per the descriptions below.

Field
Description

Policy Name

The name of your policy.

Description

Information useful for describing the purpose or context of your policy.

Users

A list of identity provider users who will be authorized to use this policy.

Groups

A list of identity provider groups who will be authorized to use this policy.

Resource Type

Either an environment or a list of targets which are the resource(s) authorized for access by this policy.

Dynamic Access Targets

  1. Spin up and register a target. A target can be a server, container, virtual machine (e.g. EC2 instance), etc. The provisioning server can spin these targets up on-demand or have a pool of targets waiting to be registered; the way these machines are created is up to the provisioning server's implementation. The only requirement is that the server must install bzero agent and register itself with BastionZero on each spawned target. The server should also assign a UUID to the spawned target so that it can be torn down when it is no longer needed. When BastionZero calls out to the provisioning server, the required parameters needed to execute bzero -registrationKey on the spawned target will be provided.

  2. Tear down a target. The provisioning server must have the ability to stop and spin down the spawned targets. BastionZero will remember the UUID the server assigned in step (1) and provide the same identifier when asking the server to stop a specific target.

The provisioning server's architecture, due to being designed as POST webhooks, allows for dynamic targets without requiring BastionZero to have privileged access or special roles in an organization's cloud/network.

Why Use DATs

DATs encourage users to use ephemeral targets to access certain resources in an organization's network. Once the resources have been polluted by a user's access, the target may be torn down. For instance, one may require that any hands-on-keyboard database migration be performed from a fresh target container that is killed once the migration is complete.

Configuring DAT

Because DATs are dynamically created by querying a provisioning server, an organization administrator must first add a Dynamic Access configuration before other users in the organization can ask to connect to a DAT. Every DAT has a backing Dynamic Access configuration which determines how the target is spun up (provisioned) and torn down (destroyed).

Below is an explanation of each configuration option.

Argument
Description

Name

Environment

The environment that contains all DATs registered by the backing provisioning server. The environment determines the policies to apply to the spawned targets and therefore which users can access them.

Start webhook

The URL of the provisioning server's POST start endpoint. This endpoint is queried by BastionZero when it requests the server to spin up and register a target. Example: https://dynamic-access.example.com/start.

Stop webhook

The URL of the provisioning server's POST stop endpoint. This endpoint is queried by BastionZero when it requests the server to tear down a target. Example: https://dynamic-access.example.com/stop.

Health webhook

The URL of the provisioning server's GET health endpoint. This endpoint is queried by BastionZero periodically to check that the provisioning server is still online and accessible. Example: https://dynamic-access.example.com/health.

Shared secret (base64)

Connecting To A DAT

Once the Dynamic Access configuration has been added, authorized users, as defined by the organization's policies, can connect to a DAT provisioned by the server specified in the configuration.

Connecting Via the zli

To connect to a dynamic access target via the zli, a user executes a command similar to the following one:

zli connect ssm-user@db-dat --dynamic

db-dat is the name of the Dynamic Access configuration, and ssm-user is a default user that exists on all DATs. The user can specify a username not equal to ssm-user as long as the specified username actually exists on the provisioned machine, and there exists a policy that allows access to such Target User.

DATs Vs. Targets

DATs differ from standard SSH targets in three ways:

  1. How they are discovered and initially connected to by BastionZero.

  2. The lifetime of DATs.

  3. The policies involving DATs.

Discovery and Initial Connection

Unlike SSH targets, which are discovered by BastionZero once an administrator installs the bzero agent, DATs are discovered on a per-user basis when the user asks to connect to a DAT. A single user cannot have more than one DAT target created by the same Dynamic Access configuration. The name of discovered DATs hint at this exact property: DAT-<name-of-dynamic-access-config>-<User's full name>.

When processing the connect request, BastionZero sends a POST request to the start webhook as defined in the Dynamic Access configuration. This request notifies the provisioning server that a fresh target should be created.

Because it can take the provisioning server some time to spin up a target, the terminal shell that appears after making the initial connection will be in the loading state. The shell cannot receive any input until the target is fully provisioned - that is until the target is fully registered, online, and reachable by BastionZero.

This initial connection experience is different than when connecting to an SSH target because of the nature of a DAT. A DAT's existence is known at the time of an initial, user-initiated connection. An SSH target, on the other hand, is known at the time of registration, which happens during the autodiscovery process. Due to this difference, an initial connection to a DAT will often take longer than when connecting to an SSH target whose existence is already known ahead of time.

Notice, however, that once the initial connection is made and not closed, future DAT connections made by the same user who initially connected, will finish connecting much faster than before. This is because all future connections to the same Dynamic Access configuration will connect to the already provisioned and running DAT created for the specific user.

Lifetime of DATs

DATs are meant to be used as ephemeral targets; therefore, the lifetime of a DAT is fairly short compared to an SSH target. A DAT target is automatically deleted once there are no more connections to it. When the last connection is closed, BastionZero sends a POST request to the stop webhook as defined in the Dynamic Access configuration. This request notifies the provisioning server that the backing machine should be destroyed and is no longer needed.

An SSH target, on the other hand, will not be deleted unless the user explicitly deletes it from the Targets screen or if the environment's offline target removal policy timeout is reached.

Policies of DATs

Similar to other kinds of targets, DATs are protected by the organization's policies. The two types of Target Access policies, environment-specific and target-specific, are applicable to DATs. However, there is a notable difference in a target-specific policy compared to SSH targets. A target-specific policy cannot refer to one of the spawned DATs; it can only refer to a specific Dynamic Access configuration.

The effect of this difference is as follows:

  • If the organization only has a target-specific policy for some Dynamic Access configuration, authorized users can only access the DATs created for them (i.e., the ones with the name DAT-<name-of-dynamic-access-config>-<User's full name>).

  • If an administrator wants to allow users to access DATs that were not created for them, then an environment-specific policy that refers to the Dynamic Access configuration's environment must be used.

SSH Tunnels & Secure File Copy

With BastionZero SSH tunneling, there is no need to utilize SSH keys; instead, BastionZero automatically sets up a one-time-use SSH key for each tunnel. You can then use your native SSH clients and scripts to connect to targets that are autodiscovered to BastionZero.

The figure shows the architecture for the SSH tunnel. The connection from your SSH client is routed through BastionZero's zli. The zli then creates an SSH tunnel directly to the target. The SSH tunnel is passed over a web socket from the zli to BastionZero. From there, it is passed over a different web socket from BastionZero to the target.

If a user wants to access a target via an SSH tunnel, there must a policy in BastionZero that allows that user to do so.

At this time, BastionZero does not have the ability to read the contents of the SSH tunnel so command logging is not possible with SSH tunneling. However, BastionZero logs do capture the establishment of the SSH tunnel and its duration.

Setting It Up

Run zli generate ssh-proxy and configure your .ssh/config file with two lines:

host bzero-\*
    IdentityFile /home/user/.config/bastionzero-zli-nodejs/bzero-temp-key
ProxyCommand /home/user/zli ssh-proxy -s %h %r %p /home/user/.config/bastionzero-zli-nodejs/bzero-temp-key

For simple access, just prefix the host with bzero:

$ ssh ssm-user@bzero-centos-machine1

You can tunnel to a remote server application using the below.

$ ssh -L 6100:127.0.0.1:5432 ssm-user@bzero-postgresDB

You can also tunnel using a client browser to reach an HTTP application on your local network.

$ ssh -L 8080:10.0.0.1:80 ssm-user@bzero-httpRedirectServer

If you don't have the zli installed on your machine yet, from your terminal, run /bin/bash <(curl -fsSL https://download-zli.bastionzero.com/scripts/install-zli.sh) or see our for installing the zli.

Once Quickstart is complete, connect to your targets using our .

Fast forward to agent registration | Register the agent with BastionZero. See the full list of bzero arguments . The agent must be run as root.

They are multi-use (you do not need to create a new key for every target registered) and should be stored in a secure place, such as a vault. Learn more about the role registration keys play in BastionZero .

For more detailed information regarding how to generate or retrieve your secret and what other flags are available with the registration command, take a look at our .

Fast forward to agent registration | Register the agent with BastionZero. See the full list of bzero arguments .

They are multi-use (you do not need to create a new key for every target registered) and should be stored in a secure place, such as a vault. Learn more about the role registration keys play in BastionZero .

For more detailed information regarding how to generate or retrieve your secret and what other flags are available with the registration command, take a look at our .

Install the Helm chart. This will install and register the bzero agent in your cluster. Refer to the tables below for a . The command below is a base for you to expand on as desired.

Now that your agent is registered , update your to configure which SSO users have access to your cluster.

They are multi-use (you do not need to create a new key for every target registered) and should be stored in a secure place, such as a vault. Learn more about the role registration keys play in BastionZero .

For more detailed information regarding how to generate or retrieve your secret and what other flags are available with the registration command, take a look at our .

Helm does not automatically update the Helm chart when there are new changes. Check our latest to stay up to date.

(optional, but STRONGLY recommended) The specific version of the BastionZero agent to be downloaded using Helm. Refer to to find the most recent version.

to specify the agent version explicitly. See for the most recent version.

If you set the image.agentImageTag when installing via Helm, then you can use helm upgrade to update this value and upgrade the agent to a newer :

If you are installing for the first time using Helm, you can append the replicaCount flag to your command.

This file tells your Kubernetes cluster to run 2 replicas of the BastionZero agent and guarantees that they will be scheduled on nodes with different labels.

If you are installing for the first time using Helm, you can append the -f multiple-replicas.yaml flag to your command.

Therefore, it is recommended to store the registration key as a Kubernetes secret and to follow best practices on protecting this Kubernetes secret as outlined . For example, you should limit RBAC access to view this secret and prevent others from creating pods or deployments in the namespace you install the agent in.

Now that your agent is registered, update your to configure which SSO users have access to your cluster. If you intend to access the cluster yourself, you will also want to update your so you can connect through BastionZero.

Log in to the .

Open a new tab or window and navigate to our . This link will open directly to the entry for generating the Bash autodiscovery script.

To specify which environment to add your target to, switch to the window containing the BastionZero web app. Navigate to the . Click the box in the top left corner that reads "Display: UUID." Copy the corresponding environment UUID from the web app into the environment ID field in the API specification.

Log in to the .

Open a new tab or window and navigate to our . This link will open directly to the entry for generating the Ansible autodiscovery script.

You will see one field for environment ID. To specify which environment to add your target to, switch to the window containing the BastionZero web app. Navigate to the . Click the box in the top left corner that reads "Display: UUID." Copy the corresponding environment UUID from the web app into the environment ID field in the API specification.

BastionZero's Windows agent supports Windows Server 2019 and 2022 as well as Windows 10 and 11 Pro. Use the Windows agent to configure both .

Fast forward to agent registration | Register the agent with BastionZero. See the full list of agent arguments .

They are multi-use (you do not need to create a new key for every target registered) and should be stored in a secure place, such as a vault. Learn more about the role registration keys play in BastionZero .

For more detailed information regarding how to generate or retrieve your secret and what other flags are available with the registration command, take a look at our .

They are multi-use (you do not need to create a new key for every target registered) and should be stored in a secure place, such as a vault. Learn more about the role registration keys play in BastionZero .

If you do not have an existing secret, instructions on how to generate a registration secret are .

If you already have a registration secret but are unable to access it, administrators can retrieve the default secret from an or by using the . Please contact your BastionZero administrator if this is the case.

(optional) The uuid of the existing environment you want to put the agent in. This flag will not create a new environment for you. If environmentId is not provided, the target will be placed in the default environment and can be assigned a new environment via .

(optional) The unique identifier for your SSO instance. In Google, it’s referred to as . In Microsoft, this is the . In Okta or OneLogin, this is the unique component of your domain: https://[orgId].okta.com. and https://[orgId].onelogin.com. In Keycloak, this is your realm's whole domain URL which can be found in the OpenID configuration in realm settings.

It is the provisioner's responsibility to use a to request the one time activation code from BastionZero. The activation code is used by the agent to identify itself to BastionZero as a resource within a specific organization. If an issue arises, bzero agents support error handling and recovery as part of the registration and activation process.

The specific provisioning implementation is described in greater detail below in .

Looking for how to connect to your resources instead? See in the User Guide.

on your client machine.

on your Linux server.

.

The bzero agent can be installed on your remote server in a variety of ways: and package managers, , , or .

Once the agent is installed on your target, it needs to register with BastionZero. If you've installed it using Bash, Ansible, or zli Quickstart, this process is already completed for you. For package managers, the registration process is detailed under and .

The Bash script implements the autodiscovery process. Using your organization's default registration secret, or an administrator's registration secret, the script will request an activation token from BastionZero and then phone home to the service with an outbound connection. Registration in this case does not require any additional action from you. See for more about registration API keys.

BastionZero supports installing the bzero agent via an Ansible playbook. The Ansible playbook implements the autodiscovery process. Using your organization's default registration secret, or an administrator's registration secret, the playbook will request an activation token from BastionZero and then phone home to the service with an outbound connection. Registration in this case does not require any additional action from you. See to learn more about generating a registration API key.

on your client machine.

on your proxy (further explained below).

.

.

If you are looking to set up passwordless database access, see our how-to guides .

The bzero agent can be installed on your database proxy target in a variety of ways: and package managers, , , or .

Once the agent is installed on your proxy target, it needs to register with BastionZero. If you've installed it using Bash, Ansible, or zli Quickstart, this process is already completed for you. For package managers, the registration process is detailed under and .

We recommend installing via , and is supported as well. Make sure to complete the to ensure the agent is registered with BastionZero.

Database target configuration is part of the "Create" function on the BastionZero web app, or you can use the . The "Create" target screen in the web app is shown below:

on your client machine.

on your Kubernetes cluster.

.

To install the bzero agent, we recommend using . is also supported.

If you're using Helm, you'll need a registration secret to install and register your agent. You can find those instructions .

See for more details and helpful tips on connecting to Kubernetes targets.

on your client machine.

on your Windows server.

, which could be an RDP target and/or a SQL Server target.

Once those tasks are completed, navigate to the and log in to your organization. You should see an online agent of type "Windows" with the hostname of your Windows server.

If you have not already created the environment you want your Windows agent in, navigate to , and press the "Create" button in the top righthand corner. Select "Environment." Fill in the name, description (if desired), and set your offline target removal policy if you want a duration other than 90 days.

Navigate back to your tab, locate your Windows agent, and click the pencil icon on the far right. Modify the environment field to be your desired environment.

Navigate to the in the web app, and press the "Create" button again in the top righthand corner. Select "Policy."

See for more details and helpful tips on connecting to Windows targets.

on your client machine.

on your proxy (further explained below).

.

.

The bzero agent can be installed on your web server proxy target in a variety of ways: and package managers, , , or .

Once the agent is installed on your proxy target, it needs to register with BastionZero. If you've installed it using Bash, Ansible, or zli Quickstart, this process is already completed for you. For package managers, the registration process is detailed under and .

We recommend installing via , and is supported as well. Make sure to complete the to ensure the agent is registered with BastionZero.

The web target configuration is part of the "Create" function on the BastionZero web app, or you can use the . The "Create" target screen in the web app is shown below:

Dynamic access targets (DATs) are machines discovered by querying a provisioning server that runs outside of BastionZero. The targets are dynamic because given a specific , the state, and number of targets online are constantly changing. The provisioning server has two main responsibilities:

Both of these functionalities should be abstracted behind two distinct HTTP POST endpoints, which the provisioning server must implement. Details on the full API specification, including a Python Flask reference implementation, is available .

An organization administrator has the ability to add a Dynamic Access configuration in the Create dropdown menu found in the top-right corner of the .

A unique name that is used to refer to this Dynamic Access configuration. This is the name that appears in the Targets screen and Connect screen on the BastionZero web app. It is also the name that is used when a user wishes to connect to a DAT .

A shared secret between the provisioning server and BastionZero that is used to ensure only BastionZero is authorized to query the provisioning server. See more details in the reference specification's README found .

Once a DAT is fully provisioned and registered, a DAT does not appear differently from the user's perspective. It is listed as an SSH target in the list of the organization's targets (Targets screen), and the user connects to it through the same flow as described . In fact, the provisioned target is running the same bzero agent that is installed when registering a target via any .

To configure your server target to utilize tunnels or file copy, ensure the BastionZero agent is already .

For more information on SSH tunnels, check out the .

guide
connections guide
below
here
registration overview
below
here
registration overview
complete list of Helm arguments
🎉
Kubernetes policy
here
registration overview
release
docker
version
helm install
topology.kubernetes.io/zone
helm install
here
Kubernetes policy
kubeconfig
BastionZero web app
API specification
environments tab
BastionZero web app
API specification
environments tab
RDP targets and SQL Server targets
below
here
registration overview
here
here
autodiscovery script
API
registration API key's secret
Installation by Use Case
Connecting To Your Resources
Download the zli
Install and register the bzero agent
Author policy for users to access your server
yum
apt
Bash script
Ansible playbook
zli Quickstart
yum
apt
here
here
Download the zli
Install and register the bzero agent
Configure your database target
Author policy for users to access your database
here
yum
apt
Bash script
Ansible playbook
zli Quickstart
yum
apt
Helm
YAML
Kubernetes setup
API
Download the zli
Install and register the bzero agent
Set up your Kubernetes policy
Helm
YAML
here
here
Download the zli
Install and register the bzero agent
Ensure your Windows agent is in the right environment.
Author policy for users to access your Windows target
BastionZero web app
Environments
Targets
Policies tab
here
Download the zli
Install and register the bzero agent
Configure your web server target
Author policy for users to access your web server
yum
apt
Bash script
Ansible playbook
zli Quickstart
yum
apt
Helm
YAML
Kubernetes setup
API
Dynamic Access configuration
here
BastionZero web app
above
autodiscovery method
installed, registered, and online
SSH tunneling man page
Access for Infrastructure
Install the bzero agent
Register the agent
here

ZLI Quickstart

A guided 4-step process from the ZLI

Yum

Recommended for RHEL, Fedora, CentOS

Apt

Recommended for Debian, Ubuntu

Helm

Recommended for Kubernetes

YAML

Another option for installing the Kubernetes agent

Bash

A Bash script to install bzero

Ansible

An Ansible script to install bzero

Windows

A guide to install on your Windows servers

Terraform

A guide to install bzero using Terraform

Helm Upgrade

A guide to upgrading your Kubernetes agent

Kubernetes Multi Replica & High Availability Support

A guide to creating a highly available Kubernetes target with multiple agent replicas

Servers

Secure access to your Linux server

Databases

Secure access to your databases

Kubernetes

Secure access to your Kubernetes clusters

Windows Servers

Secure access to your Windows servers (RDP & SQL Server)

Web Servers

Secure access to your web servers

Dynamic Access Targets

Secure access to ephemeral servers

SSH Tunnels, SCP, & SFTP

Secure access to SSH tunnels and file copy

Video shows using zli quickstart to secure 2 SSH hosts with BastionZero.
docker
cloud.bastionzero.com
orgID
tenantID
via the zli
here
Diagram of autodiscovery flow in BastionZero
Database Access Through Kubernetes Architecture
Proxy Policy
List of targets within a Kubernetes cluster that is secured by BastionZero
Example of a Kubernetes policy
An online Windows agent in the BastionZero cloud app
Example of the different types of access you can grant for WIndows targets
This example policy grants the Product org RDP and SQL Server access to any Windows agents in the Desktop App environment.
Webserver Architecture
Webserver Access Through Kubernetes Architecture
Proxy Policy
Image of a DAT configuration
Diagram of ssh tunneling in BastionZero