Desktop App Capabilities and Components
- Updated on Aug 09, 2022
- Banyan Desktop app capabilities
- Desktop app components
Banyan’s desktop app allows end users to register their devices with Banyan and access Banyan-secured services.
Banyan Desktop app capabilities
The Admin Service (banyanapp-admin) accounts for any functionalities in the Banyan app that require administrative privileges. It’s installed alongside the app (by the installer) and run as a service on the machine. It functions independently but contains select command line utilities in the case of an emergency.
In order for end users to connect to Service Tunnels, the Banyan app must install the
WireGuard Service which creates and maintains the WireGuard tunnel interface. This one-time installation requires admin privileges and is triggered when an end user connects to their first Service Tunnel. The service runs on port
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.
Banyan Proxy Service
In order for end users to access Infrastructure Services, they need to use the
banyanproxy component of the desktop app. When an admin runs the installer, the 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.
banyanproxy executable location depends on the Operating System in use:
|Operating System||Executable Location||Symbolic Link Location|
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.
banyanproxy has the following capabilities, in order to support any type of TCP client and service:
||In this mode,
||Operates similar to SSH Mode, except that banyanproxy is listening for client network connection rather than stdin/stdout. Designed for TCP client/server communication.|
||In this mode,
One-click SSH access
Admins can define an SSH service for end users. Now, when end users select 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|
When an end user connects to an SSH service, the app places Banyan’s SSH configurations in a file called
bnn.config in the SSH config location. The app also adds the SSH
Include command to the
.config file to incorporate Banyan’s SSH configurations.
Prior to Desktop app v3.0.0, the app would place Banyan’s SSH configurations in a file called
banyan.config. In Desktop app v3.0.0 and later, the app places Banyan’s SSH configurations in a file called
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
Admins can define a Kubernetes service for end users. Once completed, and end users connect to the Kubernetes API service, the desktop app will automatically create the Kube Config file with the
banyanproxy and token settings needed.
The Kubernetes config location depends on the Operating System of the device:
|Operating System||Kube Config Location|
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, end users can set the
KUBECONFIG env variable and then 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 end users are using an older version of
kubectl, they will need to add
https_proxy env var in front of their
Desktop app components
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. In this scenario, the end user must stop the application that is using port 8118 before the desktop app authentication flow can proceed.
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|
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
Banyan’s desktop app places the certs and key files in a specific directory depending on your Operating System. Since 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|
Admins can use standard
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 email@example.com", CN = Banyan Client firstname.lastname@example.org 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: email@example.com user certificate Public key: RSA-CERT SHA256:yv/nypkONDQF+rS8pJd5pJvItB7Y7wol1KjJfIxhMdE Signing CA: RSA SHA256:LGvtbCthk48jqxuggCJKAw6stao7VDIvd2OuRipczcs Key ID: "firstname.lastname@example.org 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
Can’t find what you’re looking for?
We’re happy to help. Contact our team.