Customize the Look and Feel

The Curity Identity Server comes with a powerful system for customizing the branding per OAuth client. The user-facing screens can be tailor-made to match your needs. For example, if your organization has several brands this can be embedded, and the user presented with a specific brand depending on where they are. The templating system enables an overlay possibility of existing templates with your choice of colors, logos and fonts. Making it possible to completely style the look and feel.

The UI Builder

The Curity Identity Server installation comes bundled with a UI Builder. It is a small toolkit that can be used when customizing the templates. It contains both a previewer that can serve the Velocity templates without the server running, as well as the source code for all templates and styles.

Get started

Prerequisites

• Node.js 8 or later
• Java 11 or later

npm, the Node package manager, the npm Registry, and npm CLI is distributed with Node.js – which means that when you download Node.js, you automatically get npm installed on your computer.

Install and run

Inside <IDSVR_INSTALLATION>/misc/ui-builder:

1. npm install
2. npm start
3. Open http://localhost:3000/ in your browser.

Template System

All screens that are presented to the user are based on templates. The Curity Identity Server uses the Velocity templating language to allow for reusability between screens. The templates use a pre-defined hierarchy that can be reused if desired. However the system allows for freedom to customize everything with your own template hierarchy.

Example of the template system and folder structure

├── core
├── overrides
│   └── fragments
│       └── logo.vm (overridden template)
└── template-areas
    ├── brand-1
    │   └── settings.vm (custom settings, css theme etc)
    └── brand-2
        └── settings.vm (custom settings, css theme etc)

Variables

Some screens are controlled by Velocity variables. For example to set a custom logo, you can set your own logo like this: #set ($logo_path = "/images/company-logo.svg")

Read more about Velocity templates in the docs

Overriding templates

If you want to create a template that will override an existing core template, create a copy in the overrides directory following the same structure as the core templates. As a simple example, to override the fragments/logo.vm, copy it to overrides/logo.vm and make your changes.

Template areas

Just like overrides, all the variables and templates can be overridden. But with template areas you can customize branding for different OAuth clients.

Read more about overrides and template areas in the docs

UI Design

All the design like colors, white space, media queries is defined with CSS and with the Curity Identity Server this gives you complete creative freedom. You can customize everything.

Dark and light colors

A basic set of light and dark theme options come shipped by default. By changing these to variables in template-areas/my-company/settings.vm you can quickly switch between a light and dark skin.

 #*
  Background color.
  body-light = White background color
  body-dark = Dark background color
*#
#set ($body_background = 'body-light')

#*
  Login form background color
  form-light = White background around form
  form-transparent = Transparent around form
*#
#set ($login_form_background = 'form-light')

Example of the light and dark styles in the default theme.

Creating a CSS theme

The UI Kit themes is written in Sass (.scss). Sass is a mature, stable, and powerful CSS extension language. You can quickly modify a theme using variables for colors, white space, media queries, authenticator brand colors and more.

First make a copy of the the default curity-theme.scss to my-company-brand.scss.

Add the scss file to config.js in the scss → files array.

scss: {
	src: './src/curity/scss/**/**/*.scss',
	files: ['./src/curity/scss/main.scss', './src/curity/scss/curity-theme.scss', './src/curity/scss/my-company-theme.scss']

Now our custom theme will compile to css/my-company-brand.css

Changing theme variables

On the top you see different Sass variables that can be changed. For example, change the primary brand color using the $primary variable.

Custom css

At the bottom you see some empty class definitions, modify this to fit your company brand.

Create a template area

To create a template area, start by creating template-areas/my-company/settings.vm

This file contains the settings for our custom logo, custom css theme etc.

#set ($logo_path = "/images/hm-logo.svg")
#set ($theme_css_path = $!_staticResourceRootPath + '/css/my-company-brand.css')
#set ($main_css_path = $!_staticResourceRootPath + '/css/main.css')

Now you can preview your template area by appending ?area=my-company to the URL.

Example:

Customize using CSS

Now the fun part, let’s do some custom design! With a couple of changes to the variables for colors and font settings you can make big changes to the look and feel. All it takes is a few lines of custom css.

Dark or light theme

Depending on if you are using the built in light or dark theme setting $body_background in template-areas/my-company/settings.vm you can refer to these corresponding classes:

// Light body background (#set ($body_background = 'body-light')
.body-light {

}
// Dark body background (#set ($body_background = 'body-dark'))
.body-dark {

}

// Form background-color light. Ex. When using dark body background. (#set ($login_form_background = 'form-light'))
.form-light {

}

// Form background-color transparent. #set ($login_form_background = 'form-transparent')
.form-transparent {

}

Sass Variables

On top of your ./src/curity/scss/my-company-theme.scss you’ll find different Sass variables to modify your theming needs.

Example:

$primary: #cea05d;
$paragraph-color: #6a07d4;
$heading-color: blue;
$strong-color: rgba(0,0,0,.5);
$link-color: darken($primary, 20%);

Common classes

Other common classes that you can use:

// Base button
.button {

}

// Button hover
.button:hover {

}

// Logo
.login-logo {

}

// Login symbol
.login-symbol {

}

An example theme, using a background image, or a coloured background color.

Using external fonts

If you want to use hosted web fonts via for example Google Fonts, Typekit or similar services you need to extend this using 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 src/curity/templates/core/fragments/csp.vm to our template area in src/curity/templates/template-areas/my-company/fragments/csp.vm

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

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

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

In our custom theme src/curity/scss/my-company-theme.scss:

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

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

Summary

In this tutorial we setup a template area to take advantage of all the customization features in Curity Identity Server. We walked through template override system with variables and fragments. With a few lines of css we made a custom theme. And in the same way we can continue making more brand themes that can be used depending on where the user is. Read more in the docs