Implementing White-Labelling

Sometimes (very often in my experience) you need to support white-labeling of your application. You may normally run it in a SaaS fashion, but some important or high-profile clients may want either a dedicated deployment, or an on-premise deployment, or simply "their corner" on your cloud deployment.

White-labelling normally includes different CSS, different logos and other images, and different header and footer texts. The rest of the product stays the same. So how do we support white-labelling in the least invasive way possible? (I will use Spring MVC in my examples, but it's pretty straightforward to port the logic to other frameworks).

First, let's outline the three different ways white-labelling can be supported. You can (and probably should) implement all of them, as they are useful in different scenarios, and have much overlap.

• White-labelled installation — change the styles of the whole deployment. Useful for on-premise or managed installations.
• White-labelled subdomain — allow different styling of the service is accessed through a particular subdomain
• White-labelled client(s) — allow specific customers, after logging in, to see the customized styles

To implement a full white-labelled installation, we have to configure a path on the filesystem where the customized CSS files and images will be placed, as well as the customized texts. Here's an example from a .properties file passed to the application on startup:

styling.dir=/var/config/whitelabel
styling.footer=©2018 Your Company
styling.logo=/images/logsentinel-logo.png
styling.css=/css/custom.css
styling.title=Your Company

In Spring/Spring boot, you can server files from the file system if a certain URL pattern is matched. For example:

@Component
@Configuration
public class WebMvcCustomization implements WebMvcConfigurer {
  @Value("${styling.dir}")
  private String whiteLabelDir;

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/whitelabel/**").addResourceLocations(whiteLabelDir);
  }
}

And finally, you need to customize your HTML templates, but we'll get to that at the end, when all the other options are implemented as well.

Next, are white-labelled subdomains. For me, this is the best option, as it allows you to have a single installation with multiple customers with specific styles. The style depends solely on the domain/subdomain the service is accessed through.

For that, we'd need to introduce an entity, WhitelabelStyling and a corresponding database table. We can make some admin UI to configure that, or configure it directly in the database. The entity may look something like this:

@Table("whitelabel_styling")
public class WhitelabelStyling {
    @PrimaryKey
    private String key;
    @Column
    private String title;
    @Column
    private String css;
    @Column
    @CassandraType(type = DataType.Name.BLOB)
    private byte[] logo;
    @Column
    private String footer;
    @Column
    private String domain;

   // getters and setters
}

The key is an arbitrary string you choose. It may be the same as the (sub)domain or some other business-meaningful string. The rest is mostly obvious. After we have this, we need to be able to serve the resources. For that, we need a controller, which you can see here. The controller picks up a white-label key and tries to load the corresponding entry from the database, and then serves the result. The controller endpoints are in this case /whitelabel-resources/logo.png and /whitelabel-resources/style.css.

In order to set the proper key for the particular subdomain, you need a per-request model attribute (i.e. a value that is set in the model of all pages being rendered). Something like this (which refreshes the white-label cache once a day; the cache is mandatory if you don't want to hit the database on every request):

@ModelAttribute("domainWhitelabel")
public WhitelabelStyling perDomainStyling(HttpServletRequest request) {
    String serverName = request.getServerName();
    if (perDomainStylings.containsKey(serverName)) {
        return perDomainStylings.get(serverName);
    }
    return null;
}

@Scheduled(fixedRate = DateTimeConstants.MILLIS_PER_DAY)
public void refreshAllowedWhitelabelDomains() {
     perDomainStylings = whitelabelService.getWhitelabelStyles()
            .stream()
            .collect(Collectors.toMap(WhitelabelStyling::getDomain, Function.identity()));
}

And finally, per-customer white-labeling is achieved the same way as above, using the same controller, only the current key is not fetched based on request.getServerName() , but on a property of the currently authenticated user. An admin (through a UI or directly in the database) can assign a white label key to each user, and then, after login, that user sees the customized styling.

We've seen how the Java part of the solution looks, but we need to modify the HTML templates in order to pick the customisations. A simple approach would look like this (using pebble templating):

{% if domainWhitelabel != null %}
  <link href="/whitelabel-resources/style.css?key={{ domainWhitelabel.key }}" rel="stylesheet">
{% elseif user.whitelabelStyling != null and user.whitelabelStyling.css != '' %}
  <link href="/whitelabel-resources/style.css" rel="stylesheet">
{% elseif beans.environment.getProperty('styling.dir') != '' and beans.environment.getProperty('styling.css.enabled') == true %}
  <link href="{{'/whitelabel/'+  beans.environment.getProperty('styling.css')}}" rel="stylesheet">
{% else %}
  <link href="{{ beans.environment.getProperty('styling.css')}}" rel="stylesheet">
{% endif %}

It's pretty straightforward — if there's a domain-level white-labeling configured, use that; if not, check if the current user has specific white-label assigned; if not, check if global installation white-labelling is configured; if not, use the default. This snippet makes use of the WhitelabelController above (in the former two cases) and of the custom resource handler in the penultimate case.

Overall, this is a flexible and easy solution that shouldn't take more than a few days to implement and test even on existing systems. I'll once again voice my preference for the domain-based styles, as they allow having the same multi-tenant installation used with many different styles and logos. Of course, your web server/load balancer/domain should be configured properly to allow subdomains and let you easily manage them, but that's offtopic.

I think white-labeling is a good approach for many products. Obviously, don't implement it until the business needs it, but have in mind that it might come down the line and that's relatively easy to implement.