Extended Look and Feel Customization with the UI Builder

The Curity Identity Server comes with a powerful system for customizing the look and feel of user facing screens. These can be tailor-made according to your needs. When getting started you can make fast edits in the Admin UI, as explained in Customize the Look and Feel. This tutorial explains how to manage more advanced use cases, such as different branding per OAuth client.

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 14 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.

Run Locally

Inside <IDSVR_INSTALLATION>/misc/ui-builder:

1. npm install
2. npm start
3. Open your browser and navigate to http://localhost:3000/.

Run from Docker

The Node.js app is also available as a Docker container, to enable a setup where you only need to run a text editor locally. First, open a terminal and create a folder, then run the following commands:

docker run --name ui-builder -d curity.azurecr.io/curity/ui-builder:latest
docker cp ui-builder:/opt/ui-builder/src/curity src-vol
docker rm --force ui-builder

Next, run the UI Builder in Docker with the following command, so that the Docker image picks up assets from locally edited files, which are mounted as a volume:

docker run --name ui-builder -p 3000:3000 -p 3001:3001 -v $(pwd)/src-vol:/opt/ui-builder/src/curity -d curity.azurecr.io/curity/ui-builder:latest

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. Using the UI Builder

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. Using the UI Builder

UI Design

All the designs like colors, white space, and media queries are defined with CSS in the Curity Identity Server, giving you complete creative freedom.

Creating a theme

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

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

Changing theme variables

Themes are built with CSS Custom Properties (sometimes referred to as CSS variables or cascading variables). 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 the 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. Some examples of avaliable variables:

:root {
  --color-text: #737373;
  --color-primary: #323c53;
  --color-info: #62818f;
  --color-danger: #ca2e2b;
  --color-warning: #e0c01c;
  --color-spot: #d859a1;
  ...
}

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

To view a complete list of all the theme variables, see Customizing the look and feel

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.

Custom CSS

Depending on if you are using the built in light or dark theme settings you can scope your styles with these corresponding body classes:

.body-light {
  // For when the standard light mode is used (default)
  // #set ($body_background = 'body-light')
}

.body-dark  {
  // When the dark mode is used
  // #set ($body_background = 'body-dark')
}

.body-dark {
  // When the dark mode and a transparent well is used, making form fields appear empty against the background color.
  // #set ($login_form_background = 'form-transparent')
  // #set ($body_background = 'body-dark')
}

.body-dark .form-transparent {
  // You can further customize the modes within the form well, if you want to make form fields appear empty against the background color.
  // #set ($login_form_background = 'form-transparent')
  // #set ($body_background = 'body-dark')
}

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: http://localhost:3000/authenticator/html-form/authenticate/get?area=my-company

CSP and 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