Branding — Nixt Server docs

The pages people sign in on, approve a device on, release their quarantined mail on and make app passwords on can carry the organisation’s own name, logo and colour, and a line of help under the form. People who see their own organisation’s name know where they are signing in, and a look-alike page has more to copy before it fools anybody.

The examples use the vsx shell function from the Quick start.

Setting it

On the console, open Settings and find Branding. As you change the name, colour and logo, a preview beside the form shows the sign-in page as it will look, light and dark. Nothing changes on the real pages until you choose Save.

From the command line:

vsx admin branding set --name 'Acme' --colour '#1d3f7a' --logo acme.svg --help-text 'Trouble signing in? Call IT on 1234'
vsx admin branding show
vsx admin branding remove-logo

set changes what it is given and keeps the rest. An empty value, such as --help-text '', takes that part away.

Part	What it may be
Name	At most 80 characters, one line.
Colour	`#rrggbb`. It colours the buttons, under white text, so it must be dark enough for white text to be read on it: a contrast of at least 4.5 to 1. A lighter colour is refused, and the answer says the contrast it has.
Help	One line under the form, at most 200 characters, such as who to call.
Logo	An SVG or a PNG, at most 200 KB. It is drawn at 40 pixels high.

What happens to a logo

An SVG is taken apart and put back together with its drawing alone: shapes, groups, gradients and their colours. Anything that could do something rather than draw is removed, with everything inside it: scripts, style sheets, event handlers, links, embedded images, foreign content, and anything that points outside the drawing. What you see in the preview after saving is what is kept.

A PNG is kept as it is, once its first bytes show it is a PNG.

Which pages carry it

A page carries an organisation’s brand when it is asked for on one of the organisation’s domains, or a name under one, such as mta-sts.example.com for example.com. On a server that holds a single organisation, every page carries that organisation’s brand.

A page asked for on another organisation’s domain carries that organisation’s brand, or none.

Who can do what

Organisation administrators set the brand. Auditors can see it. Each change is recorded in the audit log, which keeps what kind of logo there is and its size, but not the logo itself.

Over the API

Route	What it does
`GET /api/v1/tenants/{tenant}/branding`	The brand: `name`, `colour`, `help` and `logo` (`{type, data}`, its bytes in base64, or `null`), and the `version` to save against.
`PUT /api/v1/tenants/{tenant}/branding`	Save it whole against the `version` read. Leave `logo` out to keep the logo, or set it to `null` to take it away.