Customize branding per Application

When it comes to branding, there are two primary methods:

  1. Template Areas

    Template areas allow for application-specific overrides to selected Velocity templates, without the need to change every screen across the system. This enables more flexibility and control.

    Learn more about Template Areas in the Front-End Development.

  2. Themes

    Themes consist of a set of CSS variables and Velocity variables. Together, they define the overall look and feel of the application. While the default theme is applied system-wide, custom themes can be created and applied to specific template areas.

    If a theme shares the same name as a template area, both can be applied to Clients, Authenticators, Service Providers, and Authentication actions.

Customizing the Look and Feel

All the style rules of the frontend are bundled in two .css files which are included in the Curity Identity Server. Try not to override any of those files as it might be harder to follow future updates. Instead you should create your own custom-theme and include it in the templates by using the settings.vm file.

Creating Themes in the Admin UI

The theme builder inside Admin UI makes it easy to customise theming.

In order to create your own themes, follow the steps below:

  1. Go to System → Look and Feel or visit https://localhost:6749/admin/#/look-and-feel.
  2. Select whether you want to customise the default theme or you want to create a new custom one.
  3. Make customizations in the controls sidebar, you will see a preview in real time updating as you work.
  4. To save the changes click on the Commit menu option in the Changes menu.

Note

It is recommended to either use the Admin UI theme builder, or to create a custom theme in UI Builder.

The Look and feel editor

Fig. 194 You can find the theme builder under the System sidebar, click on “Look and feel”.

The Preview Area

The main preview area gives you an overview on how the templates will look in real time. Without having to switch to the server rendered templates every time. You can switch between 1) Login 2) Authenticator Selector 3) Create account.

Controls

In the right sidebar you will find all the controls. To make customizations, edit color swatches, drag sliders and make changes to default values. It is good to have basic CSS knowledge to understand some properties, but many are self explanatory and has descriptions below. Each controls maps to a CSS custom property in the Curity UI-Kit theming system. Changes are applied instantly in the preview area.

Toggle Alerts and Errors

To see how errors and alerts look like, toggle the error switch in the toolbar.

Toggle Alerts and Errors

Fig. 195 Toggle errors and alerts

View theme CSS

When you want to see the generated CSS code from the changes, switch to “View CSS” in the toolbar.

View CSS

Fig. 196 Click “View CSS” in the toolbar to see the generated CSS Code

Download CSS file

It is also possible to download the CSS file separately, if you want to drop in to an existing Curity installation or continue working on it in an IDE.

Download CSS

Fig. 197 Download the CSS file by clicking Download CSS in the toolbar menu

Edit a theme

You can select the theme you want to edit from the selector located in the toolbar.

Select theme

Fig. 198 Select the theme you want to work with

Default theme and Custom themes

The default theme is the one that will be applied system wide. It has predefined name which cannot be changed, but the values can be reset to its default values.

Reset theme

Fig. 199 Click “Reset theme” to discard the changes and go back to the default theme

Custom themes can be created each having its own name and an optional description. A custom theme can also be created by duplicating an existing theme. Removing a custom theme can be done by clicking the trash icon. The content of the custom themes can be modified in the same way as in the default theme.

Create theme

Fig. 200 Create a new custom theme dialog window

Changing the default theme results in applying it’s styles to the whole application.

Instead, the custom templates can be used to apply different styling to the different template areas. Custom themes can be applied to the template areas in the same way as the themes created by the UI Builder. I.e. for the following template areas applications:

  • Authenticator
  • Authentication actions
  • OAuth client
  • Service provider

The styling of the custom themes can be also combined with the UI Builder styling. This can be achieved by selecting the same name for the custom theme as the one created by the UI Builder. When selecting the template area form the Admin UI page, the source of the theme is indicated by a label. As an example, in the following figure the company-a theme is created by the UI Builder, the company-b theme is created by the Admin UI and the company-c theme is contains styling created by both, the UI Builder and the Admin UI.

Select template areas and themes

Fig. 201 Select template areas and themes

Velocity variables

Besides the CSS theming properties, there are some properties that sets Velocity variables.

  1. $theme_css_path - the path to the created CSS theme.
  2. $logo_path - the path to the logotype. You can upload an image (converted to a base 64 encoded string) or specify an external URL.
  3. $logo_email_path - the path to the email logotype used when sending emails. You can upload an image (converted to a base 64 encoded string) or specify an external URL.
  4. $logo_inside - the placement of the logo. It can be outside the well (default) or inside. This is a new setting from version 7.0.0
  5. $single_color_authenticator_chooser - the colors of the authenticator buttons. Colored buttons is default, but you can set a monochrome color scale.

Custom CSS

You can also write custom CSS that will be included in the theme.

Write custom CSS

Fig. 202 Switch to the CSS tab in the right sidebar to write custom CSS that will be included in the theme.

Note

The Custom CSS added here doesn’t reflect in the Preview area, but will be added when the configuration is commited.

How to create your custom theme in UI Builder

In order to create your own custom-theme, follow the steps below:

  1. Duplicate the file $INSTALLATION_HOME/misc/ui-builder/src/curity/scss/curity-theme.scss (for example to $INSTALLATION_HOME/misc/ui-builder/src/curity/scss/custom-theme.scss)
  2. Start the previewer (see Using the UI Builder), so that the custom-theme.css file is created under $INSTALLATION_HOME/misc/ui-builder/build/curity/webroot/css
  3. Change the values of the variables defined in the copied file to ones that fit your needs

The next step would be to include the custom-theme.css file that you previously created in the templates. In order achieve that:

  1. Copy the $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/core/settings.vm file under $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/overrides/
  2. Uncomment the row referring to the loaded theme (search for $theme_css_path) and change curity-theme.css to custom-theme.css
  3. Restart the previewer (this will force the previewer to include the newly copied in the $INSTALLATION_HOME/misc/ui-builder/build folder)

You can now continue editing the custom-theme.scss file and the changes will be reloaded on the previewer without the need for restart. Avoid changing other .scss other than the custom-theme.scss when possible. You can add your CSS overrides at the end of the file which will take precedence over any rules in main.css

Danger

Never override csp.vm with an empty file or one that substantially reduces the policies defined by that core template. Doing so will likely result is severe security vulnerabilities.

How to work with Sass

The Curity UI Kit is written in Sass (.scss). Sass is a mature, stable, and powerful CSS extension language. Sass is a preprocessor and compiles to CSS. Sass has features that help you write robust, maintainable CSS.

Sass compiles to CSS so every file inside src/curity/scss/ will compile to a .css file, ready to be included in HTML.

Main

The main file - src/curity/scss/main.scss contains base styles for all the application components aswell as some settings defined as Sass variables, such as the path to fonts and media queries.

Font path

When using self hosted webfonts the $fontPath variable sets the path to those fonts.

Media Queries

To work with responsive themes there are predefined breakpoint variables. Curity UI Kit uses a mobile first strategy using min-width media queries. Any CSS unit can be used here, rem, em or pixels are preferred.

1
2
3
4
5
6
$breakpoint-sm: '(min-width: 40em)' !default;
$breakpoint-md: '(min-width: 52em)' !default;
$breakpoint-lg: '(min-width: 64em)' !default;
$breakpoint-xlg: '(min-width: 74em)' !default;
$breakpoint-xxlg: '(min-width: 84em)' !default;
$breakpoint-xxxlg: '(min-width: 114em)' !default;

Themes

Themes are built with CSS Custom Properties (sometimes referred to as CSS variables or cascading variables), so not relying on any Sass syntax or special features. Theme files contains only a list of properties, using the custom property notation (key/value). --color-spot: #d859a1; and are accessed using the var() function (e.g., color: var(--main-color);). Since themes are created with CSS Custom Properties, this also means that the variables can be easily modified with JavaScript and also created outside UI Kit, all you need is a text editor.

Curity themes follow a common best practice that is to define custom properties on the :root pseudo-class, so that it can be applied globally across your HTML document.

UI Kit comes with a default theme curity-ui-kit/src/curity/scss/curity-theme.scss.

Theme variables

A theme consists of different sets of variables to style different components in the application.

  1. Page - top level styles to modify the top level page area, surrounding the well.
  2. Well - the container that holds the form elements
  3. Login symbol - the illustrative icon on top of the form
  4. Logo - the company logo
  5. Colors - Main color such as primary, call to action and spot colors
  6. Forms - Style form elements
  7. Typography - Change font settings, such as pointing to system fonts or web fonts
  8. Spacing - Space between component follow a vertical rythm.
  9. Progress bar - The HTML progress element used for password strengh checker
  10. Buttons - Button components and variants
  11. Alerts - Holds inline warnings, errors and success messages
  12. Checkmark - Style the animated checkmark that is used on templates where a flow is “done”.
  13. Authenticators - Define custom colors for the avaliable authenticators.

Below you will find all the theme variables listed.

Page

The page surrounding the login well and form.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
/* If using background image, specify the URL here using url("URL"). Local or external. */
--page-background-image-url: none;
/* If using a css gradient as background, supports linear, radial or conic gradient */
--page-background-image-gradient: none;
/* If using background image, specify position here x, y */
--page-background-position: center center;
/* If using background image, specify repeat;  */
--page-background-repeat: no-repeat;
/* If using background image, specify size;  */
--page-background-size: cover;
/* Page background color */
--page-background-color: #f3f5f7;
/* Page background color when the dark background setting is used */
--page-background-color-dark: #3a445e;
/* Set to none to hide the "Powered by Curity" in the footer  */
--page-powered-by-display: flex;

Well

The well is the wrapper around the form elements.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/* Border color */
--well-border-color: transparent;
/* Border radius */
--well-border-radius: 26px;
/* Border style */
--well-border-style: solid;
/* Border width */
--well-border-width: 1px;
/* Box shadow */
--well-box-shadow: rgb(0 0 0 / 5%) 0 6px 24px 0, rgb(0 0 0 / 8%) 0 0 0 1px;

Login symbol

The login symbol is the illustrative icon above the form.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/* Display. Set to none to hide */
--login-symbol-display: block;
/* The symbol has a squared canvas (equal width/height) */
--login-symbol-size: 180px;
/* Margin top */
--login-symbol-margin-top: 2rem;
/* Margin bottom */
--login-symbol-margin-bottom: 2rem;
/* Border radius */
--login-symbol-border-radius: 50%;

Colors

There are a number of main color variables that you can modify to quickly change the theme. Accent colors for states like hover, Call to Action colors, link colors and more. Any CSS color mode can be used.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
/* Paragraphs and lists */
--color-text: #737373;
/* Headings */
--color-heading: #262c3d;
/* Base colors */
--color-light: white;
--color-primary: #2e364b;
--color-primary-dark: #262c3d;
--color-primary-medium: #262c3d;
--color-primary-light: #7e89a8;
/* Call to action */
--color-success: #57c75c;
--color-info: #62818f;
--color-danger: #ca2e2b;
--color-warning: #e0c01c;
--color-add: #0092ff;
/* Spot and link colors */
--color-spot: #d859a1;
--color-link: #d859a1;
--color-link-hover: #87148b;

Forms

Forms are a big part of the templates and you can make fine grained adjustments in the theme.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
/* Label color */
--form-label-color: #666;
/* Labe line height */
--form-label-line-height: 2;
/* Label font size */
--form-label-font-size: calc(var(--type-base-size) * 0.85);
/* Disabled fields */
--form-field-disabled-background-color: rgb(0 0 0 / 12.5%);
--form-field-disabled-opacity: 0.5;
/* Read only fields */
--form-field-readonly-background-color: rgb(0 0 0 / 12.5%);
/* Background color */
--form-field-background-color: white;
/* Background color when dark mode is used */
--form-field-background-color-dark: var(--color-primary-dark);
/* Placeholder */
--form-placeholder-color: #ccc;
/* Border color */
--form-field-border-color: rgb(207 217 224);
/* Border color hover */
--form-field-border-color-hover: rgb(152, 152, 153);
/* Border color focus */
--form-field-border-color-focus: rgb(0 89 200);
/* Box shadow */
--form-field-box-shadow: none;
/* Box shadow focus */
--form-field-box-shadow-focus: rgb(152 203 255) 0 0 0 3px;
/* Height */
--form-field-height: 2.55rem;
/* Padding */
--form-field-padding: 0.75rem;
/* Padding left, set differently when form field icon is used */
--form-field-padding-left: 0.75rem;
/* Icon display. Set to block or flex to show. Default is none */
--form-field-icon-display: none;
/* Icon color */
--form-field-icon-color: #ccc;
/* Icon size */
--form-field-icon-size: 1.5rem;
/* Border radius */
--form-field-border-radius: 8px;
/* Border style */
--form-field-border-style: solid;
/* Border width */
--form-field-border-width: 1px;
/* Border color */
--form-field-border-color: #cfd9e0;
/* Border color when dark mode is used */
--form-field-border-color-dark: var(--color-primary-dark);
/* Caret color */
--form-field-caret-color: var(--color-primary);

Typography

Typography settings.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
/* Default font stack. Can be system fonts or web fonts. */
--type-sans: "Roboto-Regular", system, -apple-system, "Roboto", "Segoe UI",
  "Lucida Grande", sans-serif;
/* Default font weight */
--type-weight: normal;
/* Default font stack for bolder type. Used for headings */
--type-sans-bold: "Roboto-Medium", system, -apple-system, "Roboto", "Segoe UI",
  "Lucida Grande", sans-serif;
/* Default font weight for bolder type. These should use ex 700 when using system fonts. And the same
font weight as defined via the font-face rule, when using web fonts */
--type-weight-bold: normal;
/* Default font stack for monospaced fonts */
--type-mono: "SF Mono", consolas, monaco, "Courier New", courier, monospace;
/* Line height */
--type-line-height: 1.5;
/* Base font size */
--type-base-size: 1rem;

Spacing

Spacings between component use relative units fo follow a vertical rythm.

1
2
3
4
5
/* Spacing can use any CSS unit */
--space-1: 0.5rem;
--space-2: calc(var(--space-1) * 2);
--space-3: calc(var(--space-1) * 4);
--space-4: calc(var(--space-1) * 8);

Progress bar

The base settings for the HTML progress element. The progress element is used for the password strength checker on the create account templates.

1
2
3
4
/* Progress bar height */
--progress-bar-height: 6px;
/* Border radius */
--progress-bar-border-radius: 6px;

Buttons

The base settings for buttons. Note that button colors follow the primary color palette for easy theming.

1
2
3
4
5
6
7
8
/* Button top/bottom padding */
--button-padding-y: 0.6rem;
/* Bottom side padding */
--button-padding-x: 1rem;
/* Border radius */
--button-border-radius: 6px;
/* Button font size */
--button-font-size: calc(var(--type-base-size));

Alerts

Base settings for alerts. Note that alert colors use the Call to action colors for warning, danger, success and info.

1
2
3
4
5
6
7
8
/* Border radius */
--alert-border-radius: 8px;
/* Border style */
--alert-border-style: solid;
/* Border width */
--alert-border-width: 1px;
/* Border color */
--alert-border-color: #cfd9e0;

Checkmark

You can customize the animated checkmark that is used on templates where a flow is done.

1
2
3
4
5
6
7
8
/* Size */
--done-checkmark-container-size: 100px;
/* Inside checkmar size */
--done-checkmark-size: 80px;
/* Checkmark line color */
--done-checkmark-line-color: var(--color-success);
/* Checkmark circle color */
--done-checkmark-circle-color: var(--color-success);

Authenticators

You can define custom colors for the available authenticators.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
--authenticator-google-color: #4285f4;
--authenticator-pingfederate-color: #002050;
--authenticator-email-color: grey;
--authenticator-oidc-color: #f78c40;
--authenticator-group-color: green;
--authenticator-encap-color: #fbb034;
--authenticator-windows-color: #0078d7;
--authenticator-siths-color: #008272;
--authenticator-facebook-color: #3b5998;
--authenticator-twitter-color: #0077b5;
--authenticator-linkedin-color: #0077b5;
--authenticator-sms-color: #70b29c;
--authenticator-html-form-color: #626c87;
--authenticator-saml-color: #666;
--authenticator-totp-color: #4682b4;
--authenticator-github-color: #333;
--authenticator-twitter-color: #1da1f2;
--authenticator-bankid-color: #235971;
--authenticator-dropbox-color: #007ee5;
--authenticator-aws-color: #f90;
--authenticator-salesforce-color: #1798c1;
--authenticator-windowslive-color: #d83b01;
--authenticator-slack-color: #6ecadc;
--authenticator-box-color: #0061d5;
--authenticator-bitbucket-color: #205081;
--authenticator-instagram-color: #c13584;
--authenticator-signicat-color: #212831;
--authenticator-stackexchange-color: #1e5397;
--authenticator-criipto-color: #edb0ab;
--authenticator-freja-color: #48429e;
--authenticator-cgi-color: #c03;
--authenticator-duo-color: #6dc04f;
--authenticator-sign-in-with-apple-color: #000;

To use single colored authenticator colors using #set ($single_color_authenticator_chooser = true). If set to true the --color-primary color will be used. If set to false the authenticator color variables will be used. An example below:

../../_images/authenticator-colors.jpg

Fig. 203 Authenticator button icons can be monochrome or have colours (default)

Light and Dark Mode

../../_images/ui-kit-modes.jpg

Fig. 204 Light and dark mode

There are two built-in modes - light and dark. Modes are handled in the template settings using the two variables #set ($body_background = 'body-light') and #set ($login_form_background = 'form-light'). The CSS supports both modes without recompilation.

You can also override the CSS classes and write your own styles. At the bottom you see some empty class definitions, modify this to fit your application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
// Light body background class.
.body-light {

}

// Dark body background class
.body-dark {

}

// Form background-color light.
.form-light {

}

// Form background-color transparent.
.form-transparent {

}

Using External Web Fonts

If you want to use hosted web fonts via for example Google Fonts, Typekit or similar services you need to modify Content Security Policy (CSP). CSP is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks.

Copy $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/core/fragments/csp.vm to our overridden template or template area area in $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/template-areas/my-company/fragments/csp.vm

Then to allow, for example, Google Fonts, change accordingly:

1
#set ($styleSrc = "style-src 'self' https://fonts.googleapis.com 'unsafe-inline' ${nonceScriptSrc};")

1
<meta http-equiv="Content-Security-Policy" content="connect-src 'self'; font-src 'self' https://fonts.gstatic.com; $childSrc">

In your custom theme ${INSTALLATION_HOME}/misc/ui-builder/src/curity/scss/custom-theme.scss:

1
2
3
4
5
@import url('https://fonts.googleapis.com/css?family=Calistoga&display=swap');

body {
  font-family: 'Calistoga', serif;
}

Compiling Assets

In package.json there are npm scripts ready to run and build the themes.

1
2
3
4
5
6
7
8
9
{
  "scripts": {
    "start": "concurrently \" npm run java\" \" npm run dev\"",
    "build": "webpack --config webpack.config.js --mode production",
    "clean": "rm -rf build",
    "java": "node previewer",
    "dev": "webpack --config webpack.config.js --mode development --stats-error-details",
  }
}
  • Use npm start to start the development server. Live reload is included and the browser will reload and instantly reflect your changes, both for Sass and HTML changes.
  • Use npm run build to compile Sass to CSS. This will also copy assets like fonts, images and JavaScripts, to the build folder.
  • Use npm run clean to remove the build folder with the compiled assets.

How to work with the settings file

The settings.vm file under $INSTALLATION_HOME/misc/ui-builder/src/curity/templates/core has as a sole purpose to help developers modify the basic parameters of the templates with ease. Each possible setting contains the default value which, if needed, can be overridden.

As a first step, copy the settings.vm file from core to overrides (or your specific template-area). Then, for each of the settings you want to override, uncomment its line and change the value at will.

An overview of the possible variables and their default values can be found below:

  • main_css_path default: /assets/css/main.css
  • theme_css_path default: /assets/css/curity-theme.css
  • body_background default: body-light
  • login_form_background default: form-light
  • logo_path default: /assets/images/curity-logo.svg
  • logo_white_path default: /assets/images/curity-logo-white.svg
  • logo_inside default: false
  • powered_by default: true
  • single_color_authenticator_chooser default: true
  • icons_only_authenticator_chooser default: false
  • show_symbol default: true
  • page_symbol_path default: /assets/images/
  • page_symbol_path_* default: /assets/images/<symbol-name>.svg

A detailed explanation of each variable can be found in the comments before its declaration.

Warning

Overriding settings.vm is safe, but altering settings-default.vm (in overides, template-area or anywhere else) is not recommended. Also, try not to remove the line #parse("settings-defaults") from settings.vm. Doing so might cause problems in future updates.