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 8u60 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
:
npm install
npm start
- Open http://localhost:3000/ in your browser.
Docker images
Curity Identity Server is also available on Azure Container Registry. With pre-built Docker images for every new release, it will be even easier for those using Docker to get started and to manage the Curity Identity Server. Learn moreTemplate 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.
Curity Sass Components
The Curity components must be imported@import "curity-application"
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')
Main CSS Path
The `main_css_path` should be included, it contains the base css boilerplate, icons, and normalizations.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-companyCustomize 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
Let’s Stay in Touch!
Get the latest on identity management, API Security and authentication straight to your inbox.