Overlay

All applications providing UI implement the same pattern regarding styling. An overlay directory supplies organisation-specific files that are served instead of the built-in ones.

Configure the overlay directories

An overlay directory is read before the built-in files. A resource that exists in both is served from the overlay.

Two configuration parameters control this:

• overlay_dir — a single directory. In Fortified ID Access this defaults to ${system.customer_home}/overlay, so in a standard installation you can place the files there without changing any configuration.
• overlay_dirs — a list of directories, searched in the order they are defined. The first directory that contains the requested resource wins.

Example from a Forms config, using two directories.

{
  "name": "Forms",
  "config": {
    "http_context": "/forms",
    "logout_endpoint_url": "/forms/logout",
    "overlay_dirs": ["config/locale_overlay", "config/ui_overlay"],
    "flows": "@include:../flows/*/flow.json"
  }
}

Inside the overlay directory, create a folder named assets. The application requests its resources below assets/, so that is where the overlay files must sit.

How a file takes effect

Overlay files fall into two groups, and confusing them is the most common reason a change appears to do nothing.

Caution

Placing a file in the overlay is only enough when it replaces a built-in file of the same name. Any other file is inert until something points at it.

Files that take effect on their own

These replace a built-in file of the same name and are picked up as soon as they exist.

File	What it controls
css_overrides.css	Colors, buttons, links, progress bar, header, loader, and background image. Empty by default. See CSS.
ui_config_overrides.json	Names, titles, logo files, logo sizes, footer link, and per-application logo visibility. Empty by default. See UI Configuration Overrides.
favicon.ico	Site icon shown in the browser tab. Applications link assets/favicon.ico directly.
logo.svg	Primary logo. Most authentication applications ship an assets/logo.svg and use it as the header logo, so a file with this name replaces it. Applications that do not use that slot are unaffected.
locales/<code>.json	Replaces a built-in language file wholesale. To extend rather than replace, see Language translations.

Files that need a reference

These are naming conventions, not slots. The file name has no meaning to the application until you point at it.

File	How to activate it
Background image, by convention background.svg	Set --background-image in css_overrides.css. The built-in default is bg_login.svg, so a file named background.svg has no effect on its own. The image may be svg, png, jpg, or jpeg.
Negative logo, by convention logo_vit.svg	Reference it from ui_config_overrides.json, normally as app_logo for Portal, Forms, and Password Reset. No built-in file uses this name.
Any additional logo or image	Reference it from ui_config_overrides.json or css_overrides.css. Paths are relative to the application, so a file in the overlay assets folder is addressed as assets/<name>.
Custom locale files	Set localesMergePath in ui_config_overrides.json. See Language translations.

Note

Relative url() references in css_overrides.css are resolved against the directory the stylesheet was loaded from, so url('background.svg') finds a file next to it in the assets folder.

A typical organisation overlay

A complete organisation overlay usually contains these six files. The first three take effect on their own, the last three are referenced from them.

<overlay directory>/assets/
├── css_overrides.css
├── ui_config_overrides.json
├── favicon.ico
├── logo.svg
├── logo_vit.svg
└── background.svg

Add locale files when texts need changing. For guidance on sourcing the image files themselves, see Brand assets.