Multi-domain (aka Wildcard) Web Services

  • Updated on Jan 08, 2024

This article describes features that are only available in the Banyan Enterprise edition and Banyan Unlimited edition.

Multi-domain Web Service Overview

Banyan allows security policies to be applied at the granularity of a single service, or individual resources (such as APIs) under that service. So, web services are typically defined individually, a single domain at a time. For example, you might configure an individual web service at site1.web.example.com and site2.web.example.com, and define a policy to precisely specify which users and devices can access those services.

However, organizations often maintain and manage multiple services, sometimes thousands, at a time. While some services require a unique set of access restrictions, many of them require identical access restrictions. Rather than configure each service individually, you can group them and configure via a single multi-domain (a.k.a wildcard) service.

Multi-domain services use the wildcard (“*”) notation to create a single service definition that will apply to all the subdomains of a top-level domain. For example, you can create a wildcard web service at *.web.example.com, which will include site1.web.example.com, site2.web.example.com, etc.

How Multi-Domain Web Services Work

Banyan extends its existing standards-compliant OpenID Connect (OIDC) authentication for individual web services to multi-domain web services. For multi-domain Web services, TrustCookies are issued at the domain level, web.example.com.

Because TrustCookies for multi-domain Web services are issued at the domain level, you cannot define a multi-domain web service and a single-domain web service with overlapping domains. For example, you cannot define a web service for both *.web.example.com and test.web.example.com. Such overlapping definitions would result in TrustCookie mismatches and could potentially put your users into a redirect loop. If this happens, you need to disable one service and have end users clear cookies on their browser.

There are three additional standards-compliant technologies Banyan leverages to enable multi-domain services:

1. Wildcard DNS Records

Banyan leverages standard Domain Name System (DNS) wildcarding features to simplify network settings needed for multi-domain services. To route traffic for your multi-domain service, you need create a wildcard DNS A Record or CNAME pointing to your Banyan Enforcement Component.

For example, if you need to serve two multi-domain services at *.web1.example.com and *.web2.example.com via a Banyan Netagent with IP address 1.2.3.4, you only need to configure a DNS A Record for *.example.com, pointing to 1.2.3.4.

2. Wildcard SSL Certificates

Banyan automatically generates a wildcard server certificate for the wildcard domain when you define a multi-domain service. Since wildcard certificates are prone to misuse it is important to use stringent security measures when issuing and storing them. Banyan automatically rotates the wildcard server certificate every 24 hours. Further, Banyan Netagent only stores the server certificate in memory so it cannot be extracted even if a host is compromised.

3. Backend SNI Routing

Banyan leverages the standard Server Name Indication (SNI) extension to TLS to identify which individual domain within a multi-domain service definition a client needs to connect to.

Netagent parses the “frontend” domain name it receives in the SNI request, and uses a simple templating system to map it to individual “backend” service it needs to route the traffic to.

When you define a multi-domain service Banyan (such as, *.web.example.com), you also need to configure specific routing rules in the Service Spec. The BackendTarget section in the Spec specifies how Netagent should route the traffic to the specific individual service the client needs to access.

You can use the {{ .Name }} and {{ .Domain }} variables when you specify the Backend location for your multi-domain service, and Netagent will automatically populate those fields based on the incoming frontend connection. For more advanced use cases, you can set a NameDelimiter and use the generated {{ .Parts }} array. For example, if you have a multi-domain service *.web.example.com, with the BackendTarget.Name set to {{ .Name }}.internal. Then, a client request to site1.web.example.com will get automatically routed to site1.internal.

Configure a multi-domain web service

Root domains are not automatically included with multi-domain web services. Refer to our instructions to include a root domain with a multi-domain web service.

To configure a multi-domain web service in the Banyan Command Center, complete the following steps:

1. Navigate from Private Access > Hosted Websites and then select + Add Hosted Website.

2. On the service registration page, configure all applicable fields and ensure Service Domain Name contains the wildcard subdomain for your organization (such as *.web.example.com), and the appropriate Backend Domain with routing as needed.

In the Banyan app, end users will see a single wildcard web service entry. In their browser, they can enter the actual URL of the individual service they need to access without any additional certificates or commands.

See also: CORS Support


Include a Root Domain with a Multi-domain Web Service

To include a Root Domain with a multi-domain Web Service, configure a Custom Web Service and pay particular attention to configuring the following fields:

  • Service Metadata
    • domain - Set to the wildcard domain (such as *.web.example.com)
  • Service Attributes
    • tls_sni - Include the root domain (web.example.com) and the wildcard domain (*.web.example.com)
    • dns_names - Include the root domain (web.example.com) and the wildcard domain (*.web.example.com)

Can’t find what you’re looking for?

We’re happy to help. Contact our team.