Customize branding per Application¶
When it comes to branding, there are two primary methods:
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.
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:
- Go to System → Look and Feel or visit
https://localhost:6749/admin/#/look-and-feel
. - Select whether you want to customise the default theme or you want to create a new custom one.
- Make customizations in the controls sidebar, you will see a preview in real time updating as you work.
- To save the changes click on the
Commit
menu option in theChanges
menu.
Note
It is recommended to either use the Admin UI theme builder, or to create a custom theme in UI Builder.

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.

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.

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.

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.

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.

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.

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.

Fig. 201 Select template areas and themes
Velocity variables¶
Besides the CSS theming properties, there are some properties that sets Velocity variables.
$theme_css_path
- the path to the created CSS theme.$logo_path
- the path to the logotype. You can upload an image (converted to a base 64 encoded string) or specify an external URL.$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.$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$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.

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:
- 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
) - 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
- 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:
- Copy the
$INSTALLATION_HOME/misc/ui-builder/src/curity/templates/core/settings.vm
file under$INSTALLATION_HOME/misc/ui-builder/src/curity/templates/overrides/
- Uncomment the row referring to the loaded theme (search for
$theme_css_path
) and changecurity-theme.css
tocustom-theme.css
- 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.
- Page - top level styles to modify the top level page area, surrounding the well.
- Well - the container that holds the form elements
- Login symbol - the illustrative icon on top of the form
- Logo - the company logo
- Colors - Main color such as primary, call to action and spot colors
- Forms - Style form elements
- Typography - Change font settings, such as pointing to system fonts or web fonts
- Spacing - Space between component follow a vertical rythm.
- Progress bar - The HTML progress element used for password strengh checker
- Buttons - Button components and variants
- Alerts - Holds inline warnings, errors and success messages
- Checkmark - Style the animated checkmark that is used on templates where a flow is “done”.
- 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%;
|
Logo¶
Base settings for the company logo. Can be placed either outside the well or inside. Default is outside. You can customize this option in settings file settings.vm
setting the logo_inside
variable to true
or false
. #set ($logo_inside = false)
1 2 3 4 5 6 | /* If logo is visible. Set to none to hide */
--login-logo-display: block;
/* Max width */
--login-logo-max-width: 200px;
/* Max height */
--login-logo-max-height: 40px;
|
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:

Fig. 203 Authenticator button icons can be monochrome or have colours (default)
Light and Dark Mode¶

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.csstheme_css_path
default: /assets/css/curity-theme.cssbody_background
default: body-lightlogin_form_background
default: form-lightlogo_path
default: /assets/images/curity-logo.svglogo_white_path
default: /assets/images/curity-logo-white.svglogo_inside
default: falsepowered_by
default: truesingle_color_authenticator_chooser
default: trueicons_only_authenticator_chooser
default: falseshow_symbol
default: truepage_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.