Notes on Securing Web Services

Advanced concepts including OIDC Exemptions, WebSockets, and more

This article describes features that require Banyan Netagent v1.21.1+.

Overview

This article details a few advanced concepts related to securing web services.

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.

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.

You can also Add CORS Exemptions for more complex exemption rules. See more detailed examples on how to leverage OIDC-exempted paths to support and protect CORS-reliant web services.

Banyan Cookies

Netagent uses HTTP session cookies when securing web services. The primary cookie, named bnn_trust (a.k.a. TrustCookie), is issued via the OIDC flow. Other cookies are used for supporting flows:

Cookie Issued By Duration/Type Purpose
bnn_trust TrustProvider Session Contains the identity token with user & device claims
bnn_nonce After OIDC authorization 15 minutes Contains a random string used to validate authentication
bnn_return After OIDC authorization 15 minutes Returns the end user to the original path they are attempting to access

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

However, some web services may want to rely on the Banyan bnn_trust cookie to extract user and device claims for their own application logic purposes. To enable these scenarios, you can set the forward_trust_cookie parameter in the Netagent config.yaml.

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.

Layer-7 (API-Level) Controls

Banyan Policies for Hosted Web Services also provide Layer-7 (aka API-level) access controls, so you can manage access down to specific Paths and APIs.

To set up API-level controls you need to create a Custom Policy. Then, following the Banyan Policy Spec Syntax, specify the resources and actions in the in the rules.l7_access block that are a given role is permitted to access.

Because Banyan’s policies are whitelist policies, you have to explicitly list every single API or Path that a Role can access. To simplify the creation of explicit lists of APIs, we supports wildcards (*) and well as deny (!) syntax in resource field.

In a whitelist policy, access to a resource is denied unless explicitly permitted.

In the following example, the policy’s access block says users with the all-admins role can access any path on the website. Users with the all-contractors role can access every path except paths that start with /admin.

[
	{
	   "roles": [
	        "all-admins"
	   ],
	   "rules": {
	        "l7_access": [
	             {
	                  "resources": [
	                       "*"
	                  ],
	                  "actions": [
	                       "*"
	                  ]
	             }
	        ],
	        "conditions": {}
	   }
	},
	{
	   "roles": [
	        "all-contractors"
	   ],
	   "rules": {
	        "l7_access": [
	             {
	                  "resources": [
	                       "!/admin*"
	                  ],
	                  "actions": [
	                       "*"
	                  ]
	             },
	             {
	                  "resources": [
	                       "*"
	                  ],
	                  "actions": [
	                       "*"
	                  ]
	             }
	        ],
	        "conditions": {}
	   }
	}
]

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.



Last modified: Jul 15, 2021