• OIDC Flows
• OIDC Exemptions
• Banyan Cookies
  • Extract claims from the bnn_trust cookie
  • Customizing the bnn_trust cookie
• Using Curl & Other CLI Tools
• HTTP-to-HTTPS Redirection
• WebSocket Support
• Custom Certificates

This article details a few advanced concepts related to securing hosted websites.

OIDC Flows

Banyan uses OpenID Connect (OIDC) authentication flows to provide your end users secure Zero Trust access to web services. Banyan’s security mechanism is designed to be completely transparent to both the user and the service it is securing.

For Web Services, Banyan Netagent checks for an authentication session cookie bnn_trust (a.k.a. TrustCookie) in the request headers. If the TrustCookie is not present, Netagent redirects the user request to Banyan TrustProvider to authenticate and authorize the user and device using OIDC.

By default, Netagent uses the OIDC Implicit flow because it has the benefit of requiring only a single call to TrustProvider via browser redirects. For some scenarios, you may want to use OIDC Authorization Code flow instead. To do so, set the code_flow parameter in the Netagent config.yaml.

Banyan TrustProvider authenticates and authorizes the user and device using the organization’s Zero Trust policies and, if that policy is satisfied, issues an OpenID Connect JWT ID-Token, that Netagent converts to a TrustCookie and sets on the user’s browser. For details on the Zero Trust policy mechanism and cryptographic properties of the TrustCookie, refer to our docs on Policy Enforcement. Now that the TrustCookie is used when making requests, the end user is able to access the service.

OIDC Exemptions

This section details how bypass Banyan’s OIDC-based security mechanism for a web service. Please proceed with caution, and contact us for assistance.

Create service accounts, instead of expemptions, to provide access from clients that cannot be registered using the Banyan Apps - see more detailed examples in our article on programmatic access.

Use the Add CORS Exemptions button for exemption rules involving cross-origin resource sharing (CORS) - see more detailed examples in our article on CORS.

In some scenarios, you may need to exempt specific URLs or Source IPs from Banyan security policies that manage access to a web service. You can use the OIDC Exemptions to allow these types of exemptions.

A common scenario arises when Banyan Netagent is securing access to a Jenkins Automation Server. Jenkins exposes webhooks at specific paths that third-party applications (such as Github.com) can invoke to trigger a pre-defined build job. Because there is no way to add the Banyan TrustCookie to requests from Github.com, these triggers will—by default—be blocked. Instead, you can allow the webhook URLs requested by Github.com via the OIDC Exemptions feature.

1. In the Banyan Command Center, navigate to Manage Services > Hosted Services and then click + Register Service. Then, create a Standard Website.

2. Configure the applicable Service Details and Service Attributes.

3. In the Exemptions section, enter any paths or source_cidrs that should be exempted from the OIDC authentication.

In this example, we use the the paths exemption, which supports wildcards for child paths and directories. In the example above, the path /v1/webhook1 and any path starting with /v2/webhook/ are exempt from the OIDC authentication.

Banyan Cookies

Netagent uses HTTP session cookies when securing hosted website services. The primary cookie, named bnn_trust is issued via the OIDC flow and contains the Banyan JWT TrustToken. Other cookies are used for supporting flows:

By default, Netagent strips all its bnn_ cookies before forwarding them to the backend application because many applications limit the total size of request headers.

Extract claims from the bnn_trust cookie

Some backend applications may want to rely on the user and device claims in Banyan’s JWT TrustToken in the bnn_trust cookie for their own application logic purposes. You can use the Headers capability to send specific HTTP headers to the backend application - an HTTP header value may be a simple string, or be constructed using Go template syntax, such as {{.Email}}, referencing values from Banyan’s JWT TrustToken.

To set headers to send to your backend application, navigate to the Advanced Configuration section of your hosted website specification and set the values needed. Read more about the variables available and different scenarios in the spec document.

As of the Apr-2020 Release, we no longer recommend setting the forward_trust_cookie parameter in the Netagent’sconfig.yaml to forward the entire bnn_trust cookie to the backend application.

Customizing the bnn_trust cookie

The bnn_trust cookie is set via the Set-Cookie response header with the HttpOnly and Secure attributes set to ensure it is sent securely and aren’t accessed by unintended parties or script.

In some scenarios, you may want to further customize how the bnn_trust cookie is set. To do so, you can use the custom_trust_cookie setting in the Hosted Website service spec.

A common use case for the custom_trust_cookie setting is to configure the SameSite cookie behavior. Since the SameSite attribute is not specified by default, the bnn_trust cookie is not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (i.e., when following a link). To configure the bnn_trust cookie to be sent in all contexts, add the following section to your service spec:

"custom_trust_cookie": {
  "same_site": "none"
}

Using Curl & Other CLI Tools

Some users—typically developers—may need to access Banyan-secured Web services via Command Line Interfaces (CLIs), such as curl or wget. They can leverage the fact that the bnn_trust cookie is readily available via their browser’s developer tools.

As described above, when the end user accesses the Web Service from their browser they are authenticated and authorized by Banyan and the bnn_trust cookie is set. The end user can navigate to their browser’s Developer Tools > Cookies section, and then copy the bnn_trust cookie value.

The end user can place the cookie value in the Cookie header for use by the CLI. For curl, they would run the command below:

BNN_TOKEN="eyJhbG..."
curl -k -H "Cookie: bnn_trust=$BNN_TOKEN" https://site1.web.example.com/

For other types of programmatic access, you can leverage the fact that Banyan uses Mutual-Auth TLS to secure TCP Services. Simply set up a HTTP web application as a TCP Service in Banyan and leverage the fact that many CLIs natively support client certificate authentication.

HTTP-to-HTTPS Redirection

Starting in Banyan Netagent v1.35.0+, traffic from Port 80 (HTTP) is automatically redirected to Port 443 (HTTPS). This ensures end users that attempt to access a Banyan-secured web service via the HTTP URL on Port 80 get a seamless redirect to Port 443 (HTTPS) for an optimal experience.

For security reasons, if your organization would like the Netagent to not listen for unencrypted traffic on Port 80 (HTTP) or automatically redirect traffic from Port 80 (HTTP) to Port 443 (HTTPS) you can set the redirect_to_https parameter to false. In this mode the Netagent follows the HTTP Strict Transport Security standard and sets the Strict-Transport-Security header for web services so clients have to use TLS to connect. Therefore, if a user attempts to access a Banyan-secured web service via the HTTP URL on Port 80, their browser will display an error message stating the site cannot be reached.

WebSocket Support

WebSocket is an HTTP-compatible protocol that provides full-duplex communication channels over a single TCP connection, which enables real-time data transfer to and from the web server.

Banyan Netagent acts as a transparent WebSocket reverse proxy, observing the HTTP Upgrade header field that is used upgrade connections from HTTP to WebSocket. You can use the same service and policy definitions as you do for traditional web services.

Custom Certificates

Banyan manages a Private PKI (Public Key Infrastructure) to automatically issue, distribute and rotate X.509 Server Certificates for your Hosted Website services.

In some scenarios, you may wish to use your own custom server certificates and not rely on Banyan-issued certificates. For example, you may want use an existing X.509 certificate issued by a Public Certificate Authority like Let’s Encrypt or DigiCert.

When you utilize the custom certificates capability, you are now responsible for the issuance, distribution and rotation of these cryptographic files. Ensure you set up robust automation and test thoroughly.

First, download the custom certificates’ key and cert files onto the file system of the Access Tier server. We typically place custom certificates in the /etc directory.

Then, create a Custom Service. Following the Banyan Service Spec Syntax, enable the custom_tls_cert block, specifying the location the custom certificates you previously downloaded.

In the following example, we specify a custom certificate obtained via Let’s Encrypt CA for the web.example.com service.

"cert_settings": {
    "dns_names": [
    	"web.example.com"
    ],
    "custom_tls_cert": {
        "enabled": true,
        "cert_file": "/etc/letsencrypt/live/web.example.com/fullchain.pem",
        "key_file": "/etc/letsencrypt/live/web.example.com//privkey.pem"
    }
}

Now, for the service web.example.com, Netagent will look in the specified path for the custom server certificate and not rely on Banyan-issued certificates.

Can’t find what you’re looking for?

We’re happy to help. Contact our team .