Key Capabilities and Features of Banyan's Desktop and Mobile App

The Banyan Apps allow 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 Apps can be found in the Support Portal.

Even though the Banyan Apps run in user-space, an end user must have administrative privileges on their device in order to install the apps. If your users do not have admin privileges, you can use a Device Manager to distribute the Banyan Apps.

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 28 or later (certutil must be installed)

The Banyan Mobile App can be installed on the following platforms:

Platform Operating System Versions
iOS iOS 11.0 or later
Android Android 8.0 (Oreo) or later

Banyan App Features

The Banyan Apps provide the following features:

Feature Banyan Desktop App Banyan Mobile App
Device Registration for device authentication
Device TrustScoring for device posture checks
Auto-update capability so an end user can upgrade with a single click
Device Trust Verification capability to support native “sandboxed” apps (i.e., iOS/Android/MacOS/Windows apps that use WebViews for authentication and are unable to access the Banyan Device Cert placed in the device cert store or keychain)
Seamless deployment via Device Managers (coming soon)
Service bundles an end user can access and favorite  
List of Hosted Websites an end user can access
List of Infrastructure Services an end user can access  
banyanproxy to access TCP services using short-lived X.509 client certs  
Banyan CLI to run in-terminal commands and automate common tasks when accessing Banyan TCP Services  

Banyan Desktop App Capabilities

Device Registration

The Banyan Apps securely registers an end user’s device, allowing organizations to roll out a Zero Trust security model where corporate applications are only accessed by Registered Devices. By default, Banyan’s “Device Registration” flow is designed for that security model, and requires the end user to perform the following steps:

  1. Provide the Invite Code needed to register a device to an organization
  2. Authenticate with the organization’s Identity Provider
  3. Set device ownership type
  4. 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

The Banyan 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 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.

The Banyan 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 run, and the user clicks connect, 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 the Banyan 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.

Short-lived Certificates

When the 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.

The Banyan 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 clicks 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 clicks Connect in the Desktop App to connect 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.

Last modified: May 27, 2021