Key Capabilities and Features of Banyan's Desktop App
- Updated on Feb 23, 2022
Banyan’s Desktop App allows your end users to register their device with Banyan and access Banyan-secured Services.
Supported Platforms
Detailed installation instructions for your users to install the Banyan Desktop App can be found in the Support Portal.
Even though the Banyan Desktop App runs in user-space, an end user must have administrative privileges on their device in order to install the app. If your users do not have admin privileges, you can use a Device Manager to distribute the Banyan App.
The Banyan Desktop App can be installed on the following platforms:
Platform | Operating System Versions |
---|---|
macOS | 10.14 (Mojave) or later |
Windows | Windows 10 or later |
Linux | Ubuntu 18.04 or later, Fedora 34 or later (certutil must be installed) |
Banyan Desktop App Capabilities
Device Registration
The Banyan App securely registers an end user’s device, allowing organizations to roll out a zero-trust security model, whereby corporate applications are only accessible to registered devices. By default, Banyan’s “Device Registration” flow is designed for that security model, and it requires the end user to perform the following steps:
- Provide the Invite Code needed to register a device to an organization
- Authenticate with the organization’s Identity Provider
- Set device ownership type
- (Optional) Verify email address via an One Time Passcode (OTP) mechanism
Once the end user has completed these steps, a Trusted Device Certificate is issued for the device and placed in the device’s keychain or certificate manager. Read more in our article on Trusted Device Certificate management and expiration.
Browser-based Authentication Flow
Banyan’s Desktop App listens on a local port at localhost:8118
to facilitate user authentication via a browser-based standards-compliant OpenID Connect flow.
However, if the device has another application running on port 8118, the Desktop App will raise an error, displaying a message of the following type:

In this scenario, the end user must stop the application that is using port 8118 before the Desktop App authentication flow can proceed.
Configuration and Log Files
The Desktop App automatically installs a config.json
file and logs files when an end user installs the Desktop App on their device. Occasionally, when troubleshooting issues with the Banyan Desktop App, we may ask you to send us the configuration file and log file from the app.
Banyan’s Desktop App places these files in a specific directory depending on your Operating System:
Operating System | Location |
---|---|
macOS | $HOME/Library/Application Support/banyanapp/ |
Windows | %USERPROFILE%\AppData\Roaming\banyanapp |
Linux | $HOME/.config/banyanapp |
TLS Proxy
In order for your end users to access infrastructure services, they need to use the banyanproxy
component of the Desktop App. When you run the installer, the Banyan Desktop App places the banyanproxy
executable in a specific directory. Then, when the Desktop App is running, and the user connects, it launches the banyanproxy
executable to set up the connection.
The banyanproxy
executable location depends on your Operating System:
Operating System | Executable Location | Symbolic Link Location |
---|---|---|
macOS | /Applications/Banyan.app/Contents/Resources/bin/banyanproxy |
/usr/local/bin/banyanproxy |
Windows | %PROGRAMFILES%\Banyan\resources\bin |
%USERPROFILE%\AppData\Local\Microsoft\WindowsApps\banyanproxy |
Linux | /opt/Banyan/resources/bin/banyanproxy |
(n/a) |
The banyanproxy
functions as a forward proxy to establish the secure connection, using the TrustCert, between the end user’s device and the TCP service, via Banyan’s Netagent.
The banyanproxy
has the following capabilities, in order to support any type of TCP client and service.
Mode | Command | Description |
---|---|---|
SSH | banyanproxy dest_host dest_port |
In this mode, banyanproxy connects to a destination host and destination port, and sends and receives data using stdin/stdout instead of using a network connection. Used for OpenSSH client. |
TCP | banyanproxy -l listen_port dest_host dest_port |
Operates similar to SSH Mode, except that banyanproxy is listening for client network connection rather than stdin/stdout. Designed for TCP client/server communication. |
HTTP_CONNECT_DAISY_CHAIN | banyanproxy -d -l listen_port proxy_host proxy_port |
In this mode, banyanproxy forwards the client’s HTTP CONNECT request to the given proxy host and port. |
Banyan Tunnel Service
In order for end users to connect to Service Tunnels, the Banyan App must install the Tunnel Service
which creates and maintains the WireGuard tunnel interface. This one-time installation requires admin privileges and is triggered when the end user connects to their first Service Tunnel. The service runs on port 8119
.
Currently, Linux users must install the WireGuard tools manually via https://www.wireguard.com/install/. We are looking to automate this via the Banyan App in an upcoming release.
Occasionally, when troubleshooting issues with the Tunnel Service
, log files may need to be obtained from the device.
The Tunnel Service
logs are located in the following locations depending on your Operating System:
Operating System | Log Location |
---|---|
macOS | /var/log/banyan/ |
Windows | C:\ProgramData\Banyan\logs |
Linux | /var/log/banyan/ |
Short-lived Certificates
When an end user logs in via the Desktop App, a cryptographic key-pair is generated and two short-lived certificates are obtained for use in authenticating the user and device. The X.509 format TrustCert is used for Mutually-authenticated TLS. The SSH format SSHCert is used for SSH certificate authentication.
In addition to short-lived certificates, Banyan requires a valid device certificate in order to access protected services. Upon registering a device, Banyan issues a trusted device certificate to the device and places it in the device’s keychain or certificate manager.
Cert Nickname | Format | Subject CN / KeyID | Cert Filename | Private Key Filename |
---|---|---|---|---|
TrustCert | X.509 | Banyan Client ... |
login-cert.pem |
login-key.pem |
SSHCert | SSH | ssh-rsa-cert ... user |
login-key.pem-cert.pub |
login-key.pem |
Both the short-lived X.509 certificate login-cert.pem
and the short-lived SSH certificate login-key.pem-cert.pub
use the same private key login-key.pem
.
Banyan’s Desktop App places the certs and key files in a specific directory depending on your Operating System. Because these certificates are short-lived, they can be stored safely in the file system (instead of your device certificate manager).
Operating System | Short-lived Certificate Location |
---|---|
macOS | $HOME/Library/Application Support/banyanapp/ |
Windows | %USERPROFILE%\AppData\Roaming\banyanapp |
Linux | $HOME/.config/banyanapp |
You can use standard openssl
and ssh-keygen
commands to examine the short-lived certificates.
$> openssl x509 -in login-cert.pem -noout -text
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
17:dd:b3:7c:3a:aa:71:42:90:1d:a7:ab:43:db:2d:df:69:fc:52:3d
Signature Algorithm: sha512WithRSAEncryption
Issuer: O = novpntest, OU = Certificate Authority, CN = testorg Banyan Private Root CA
Validity
Not Before: Jul 2 04:57:00 2020 GMT
Not After : Jul 3 03:57:00 2020 GMT
Subject: OU = "Banyan Client carly@banyanops.com", CN = Banyan Client carly@banyanops.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
00:c7:10:a7:8d:9f:18:06:f3:4e:1f:4b:20:f6:27:
...
$> ssh-keygen -L -f login-key.pem-cert.pub
login-key.pem-cert.pub:
Type: ssh-rsa-cert-v01@openssh.com user certificate
Public key: RSA-CERT SHA256:yv/nypkONDQF+rS8pJd5pJvItB7Y7wol1KjJfIxhMdE
Signing CA: RSA SHA256:LGvtbCthk48jqxuggCJKAw6stao7VDIvd2OuRipczcs
Key ID: "carly@banyanops.com ABCD8BL00KH"
Serial: 0
Valid: from 2020-07-01T22:02:21 to 2020-07-02T21:02:21
Principals:
ANY
new-role
Critical Options: (none)
Extensions:
permit-X11-forwarding
permit-agent-forwarding
permit-port-forwarding
permit-pty
permit-user-rc
One-click SSH Access
You can define a service of type SSH for your end users. Now, when your end user selects Connect in the Desktop App to connect to the SSH service, the Desktop App will automatically update the device’s SSH Config file with the banyanproxy
settings needed.
The Desktop App uses an SSH config location depending on the Operating System of the device:
Operating System | SSH Config Location |
---|---|
macOS | $HOME/.ssh/ |
Windows | %USERPROFILE%\.ssh\ |
Linux | $HOME/.ssh/ |
When an end user connects to a SSH service, the app places Banyan’s SSH configurations in a file called banyan.config
in the SSH config location. The app also add the SSH Include
command to the .config
file to incorporate Banyan’s SSH configurations.
Prior to Desktop App 1.10, the app would write to the device’s SSH config file directly. In Desktop App 1.10 and later, the app places Banyan’s SSH configurations in a file called banyan.config
.
If the SSH Config directory or file doesn’t exist, the Desktop App will automatically create it. However, if the SSH Config file or directory is not writable, end users will see an error message when they try to connect to an SSH service.
One-click Kubernetes Access
You can define a service of type Kubernetes for your end users. Now, when your end user connects to the Kubernetes API service, the Desktop App will automatically create the Kube Config file with the banyanproxy
and token settings needed.
The Desktop App uses a Kubernetes config location depending on the Operating System of the device:
Operating System | Kube Config Location |
---|---|
macOS | $HOME/.kube/ |
Windows | %USERPROFILE%\.kube\ |
Linux | $HOME/.kube/ |
When an end user connects to a Kubernetes service, the app creates a kube config file banyan
in the Kube Config location. To make the Banyan Kubernetes Service the default method to access their cluster, your end users can set the KUBECONFIG
env variable and the use the config use-context
commands as detailed in the kubectl docs.
This feature uses the proxy-url
capability available in kubectl
v1.19+. If your end users are using an older version of kubectl
they will need to add https_proxy
env var in front of their kubectl
commands.
Run Diagnostic Tool for troubleshooting
If, in any case, end users are encountering issues (e.g., cannot access a service or register a device) and want to diagnose the issue in the Banyan Desktop App, they can use the Run Diagnostic tool. End users can also use this diagnostic tool to package logs to send to their administrator.
- Navigate from Settings > Help in your app. Select the Run Diagnostic Tool. This will pull up a Health Check panel that confirms whether you want to run a health check. Select Run.

- The Health Check menu will display a list of your device’s properties, the status of your sessions and services, and your device features (showing which security measures you have in place and whether your system is up-to-date).

- At the bottom of the Health Check menu, you’ll see a View Log Files button. Select View Log Files to download your app log.
