App white-labeling

[AlexRuiz7]

White-labeling

Supporting our partners in their commercial offerings.

Introduction

We want to make it easier for our partners and the general open source community to white-label our application interface to include their branding.

Strategy

We can use multiple strategies to allow our users to dynamically change the aspect of the UI.
Most changes will need to be made to the base wazuh-indexer and wazuh-dashboard packages, while the application will need to develop an interface to manage these changes.

Important use cases

• Use case: vendors that don’t want the users to access the customization options

  • Proposed solution: access to the customization section only for authorized roles.

• Use case: possibility to add “Powered by Wazuh” to let users know the product they are using under the hood.

  • Proposed solution: keep the About section of the app unchanged.

• Use case: internationalization. Support for different languages (not officially supported by Wazuh). Users that do want to translate the plugin without the need to modify the source code.

  • Proposed solution: extract the hard-coded texts to resource assets, which can be switched and added without source code changes.

CSS variables

Design our custom opensearch-dashboard theme to use a separate CSS that will define variables that will affect the logos, texts, colors, and fonts of the areas we want to personalize.

Their values can be overridden programmatically by style.setProperty() and the related styles change accordingly, in run-time.

Our application will need a configuration to save and restore these values on page load.
All evergreen browsers support CSS variables.
We might be able to style the favicon and support different themes too.

Requirements

Requirements

1. Wazuh dashboard - login: Logo, title, and subtitle
2. Wazuh dashboard - plugin: Drop-down icon
3. Wazuh dashboard - plugin - reports: Icon
4. Wazuh dashboard - plugin - reports: Contact info
5. Wazuh dashboard - plugin - reports: Copyright
6. Wazuh dashboard - browser tab: Title

The items above translate to the following tasks:

Prepare the app for white-labeling

• Custom branding: centralize the plugin's settings #4443
• Custom branding: add validation to the plugin's settings #4446
• Custom branding: add support to update multiple settings at a time #4450

Include white-labeling support to the app
These issues depend on the issues above.

• Custom branding-- login page
  Will be done in a next iteration, using the platform's settings.
• Add the capability of customize the logo of the app #3491 & Custom branding: assets upload #4434
• Custom branding: PDF reports #4426
• Custom branding: add customization.enabled configuration #4506
• Custom branding-- page title and favicon
  Will be done in a next iteration, using the platform's settings.

Bug fixes

• The custom logos are overlapped with Wazuh's at app start #4538

Related Issues

• https://github.com/wazuh/wazuh-kibana-whitelabeling-customer1/issues/1
• Customizable email and website information in reports #3892

Additional changes (potential requirements)

Global changes

• The plugin name (wazuh) is shown in the platform navigation drawer.
• The plugin name is used to build the URL.
• The index patterns (wazuh-alerts-*, wazuh-monitoring-*, wazuh-statistics-*)
• Programmatic navigation and redirects to /app/wazuh.
• Hard-coded wazuh … in the error messages shown by the App.
• The UI colors (light and dark themes)(background, accent)
• The fonts.

1st iteration

We'll focus on adapting the app to support white labeling in the first iteration. This means we'll provide mechanisms to upload and change the logos and text the app use as branding.

The changes related to the platform might stay out of this iteration, as we already use the built-in OpenSearch Dashboard custom branding settings for Wazuh. We need to find a way to easily enable/disable custom branding, resulting in no conflicts with the official branding.

Final testing

We'll test the first iteration as a unit when every piece has been put together.
This effort will be track in the following issues:

• Custom branding: 7.17 - QA test #4801
• Custom branding: WzD - QA test #4802

[Desvelao]

Customize the Wazuh dashboard

Built-in customizations

Wazuh dashboard is based on OpenSearch Dashboards, which supports customization through its settings:

• OpenSearch Dashboards custom branding
• OpenSearch Dashboards security plugin settings

Settings

Section	Setting
Browser tab title	opensearchDashboards.branding.applicationTitle
Favicon	opensearchDashboards.branding.faviconUrl
Branding mark	opensearchDashboards.branding.mark.defaultUrl
Branding mark (dark)	opensearchDashboards.branding.mark.darkModeUrl
Branding logo	opensearchDashboards.branding.logo.defaultUrl
Branding logo (dark)	opensearchDashboards.branding.logo.darkModeUrl
Branding loading	opensearchDashboards.branding.loadingLogo.defaultUrl
Branding loading (dark)	opensearchDashboards.branding.loadingLogo.darkModeUrl
Login logo	opensearch_security.basicauth.login.brandimage
Login title	opensearch_security.basicauth.login.title
Login subtitle	opensearch_security.basicauth.login.subtitle

Examples

These settings are working in Wazuh dashboard based on OpenSearch Dashboards 1.2.0.

Browser tab title and favicon

Login logo, title and subtitle

Loading logo

Limitations

Any changes made to the platform setting must be agreed with the @wazuh/cicd, as they are in charge of building the default settings for Wazuh Dashboard (packaging). These settings cannot be changed from the UI, but from the configuration file.

We need to discuss this in depth, and open issues to the @wazuh/cicd, so they make the required changes.

[Desvelao]

Customize the Wazuh plugin

Currently, the Wazuh plugin only supports some logo customizations.

Identify the brand references

• ✔️ plugin menu logo
• ✔️ plugin health check logo
• ✔️ plugin category logo (sidebar plugin platform menu)
• ✔️ module PDF reports logo (sidebar plugin platform menu)
• Plugin
  • name
  • id ( URL: /app/<plugin_id>, redirections)
• Plugin category
  • name
  • id
• Reports
  • Header. Default: Wazuh contact info
  • Footer. Default: Wazuh copyright
• References to products: API, agents, manager/server, plugin platform
• Index patterns
• Templates
• Colors: UI and reports

Legend
✔️ currently supported

Approach

• Add new settings to define new customizations
• Remove some unnecessary brand references replacing them with generic terms.

Enhancements

• Let the user uploads the logo assets. With this change, we should remove the possibility to define the path where the assets are exposed. This is a breaking change. ❗

[Desvelao]

In order to simplify the additions of new settings, we'll work on the settings handling section of the app. This work will be tracked in this new issue: #4443

[Desvelao]

In order to minimize the number of requests required to customize the plugin, the endpoint for such functionality will be modified to support several changes at once, with a single request.

This refactor will be tracked in this new issue: #4450

[AlexRuiz7]

Integration process for the first iteration

• Custom branding: centralize the plugin's settings #4443
• Custom branding: add support to update multiple settings at a time #4450
  • Resolved by Centralize the plugin settings #4501
• Custom branding: add validation to the plugin's settings #4446
  • Resolved by:
    • Add validation to the plugin settings #4503
    • Add multi-line validation parameters in config description #4785

These pull requests will be reviewed separately, but tested together as a unit into an integration branch. These pull request prepare the app for the white-labeling functionalities. We have named these 2 pull requests the core.

• Custom branding: assets upload #4434
  • Resolved by Upload file for customization.logo.* settings #4504
• Custom branding: PDF reports #4426
  • Resolved by Add header and footer report customization #4505
• Custom branding: add customization.enabled configuration #4506
  • Resolved by Add switch to toggle the use of custom branding #4507

After that, the white-labeling specific pull requests will be reviewed, integrated and tested one by one into the integration branch. On each iteration, only the test cases from the integrated pull request will be executed. A full regression will be executed when everything is integrated, in order to verify that there are no bugs due to the integration.

The QA flow, the pull requests dependencies and their order, have been graphically represented in the diagram below.

[AlexRuiz7]

First iteration is done

We'll open new epics (issues) for the next ones.

[ilyesm]

Hello!

Any feedback regarding the future iterations of white-labeling, regarding hard coded error messages, index patterns, fonts, colours, etc?

Thanks!

[AlexRuiz7]

Hello @ilyesm

We have a 2nd iteration currently in the backlog.

[ilyesm]

Hello @ilyesm

We have a 2nd iteration currently in the backlog.

Thanks, subscribed to that issue. Looking forward.