Handlebars Templates

The Authentication worker uses Handlebars templates to generate the HTML used in site login forms, account management pages, PIN emails, and consent messages. These templates can be overridden by named provider, provider type, and by subsite.

Default Templates

There are three different kinds of template. By default they are found at <API Server Root>\workers\auth\<version>\templates (note that this isn't a location you'll have direct access to).

Top Level Login

The top level templates provide the page header and body content of the main login form. The templates of enabled providers are pulled into this template as part of the page render.

\loginform\body.hbs
\loginform\header.hbs

Actions

These actions include the templates used for account management, mismatched (update prompt) email messages, user consent, login with link (for iCM site users) and user linking. Actions can be overridden on a per-provider or subsite basis.

\actions\accountmanagement\options\body.hbs
\actions\accountmanagement\options\header.hbs
\actions\email.link.login\emaillink\body.hbs
\actions\email.link.login\emaillink\header.hbs
\actions\email.link.login\emaillinksent\body.hbs
\actions\email.link.login\emaillinksent\header.hbs
\actions\emailupdate\body.hbs
\actions\emailupdate\header.hbs
\actions\getuserconsent\body.hbs
\actions\getuserconsent\header.hbs
\actions\twofactorauthentication\confirmationemail\body.hbs
\actions\twofactorauthentication\confirmationemail\subject.hbs
\actions\userlinking\confirmationemail\body.hbs
\actions\userlinking\confirmationemail\subject.hbs
\actions\userlinking\confirmationemailsent\body.hbs
\actions\userlinking\confirmationemailsent\header.hbs
\actions\userlinking\newuserlinkingoptions\body.hbs
\actions\userlinking\newuserlinkingoptions\header.hbs
\actions\userlinking\notificationemail\body.hbs
\actions\userlinking\notificationemail\subject.hbs

Type Specific

The header and body content of specific authentication types (Facebook, Google etc).

\types\<typeName>\header.hbs
\types\<typeName>\body.hbs

Overrides

You can customise any of the default templates using overrides. Overrides can be applied globally, by provider type (eg all Google providers), by named provider (eg a specific instance of a Google provider), and by subsite.

Override Location

The location of your overrides needs to be somewhere accessible to the API Server, which in practice means creating them in the iCM custom folder using the File Manager. The path to the override root then needs to be set in the hbTemplateOverrideRoot property of the Auth worker configuration.

While developing your override templates, set the worker's hbCacheTemplates property to false before you start. This will disable caching and let you see your changes without having to restart the API Server. This only disables caching for the overrides the worker knows about - if you create new templates in new directories you'll need to resend the API Server config. Remember to re-enable caching once you've finished.

1. Open the File Manager
2. Right-click on the top level "custom" folder and pick "Create a directory"
3. Give the directory a meaningful name. In the example below it's called auth-hbs-templates (ignore the directory called handlebarstemplates - it's used by the forms designer)
4. Update your Configuration file and add the location of the custom folder as the hbTemplateOverrideRoot
   1. In an iCM.NET environment this will be "hbTemplateOverrideRoot": "E:/iCM10/tomcat/icmresource/mnt/custom/auth-hbs-templates/"
   2. In an iCM4j environment this will be "hbTemplateOverrideRoot": "/opt/icm/tomcat/icmresource/mnt/custom/auth-hbs-templates/"

Example Override Root

Creating the following override root:

Would need the following adding to the worker configuration (in an iCM4j/Java environment):

{
    "name": "auth",
    "instances": 1,
    "threadsPerInstance": 10,
    "hbCacheTemplates": false,
    "hbTemplateOverrideRoot": "/opt/icm/tomcat/icmresource/mnt/custom/auth-hbs-templates/",
    "userProfileToObjectFieldMapping": {...},
    "providers": [...]
}

Template Resolution

Now that you have an override root, you can create the override tree. The position of files in the tree determines how they are used.

This table outlines the priority order in which the worker will look for overrides. Within each section the top path takes priority, with the default \templates\ directory checked last.

• <overrideRoot> is the root set in the worker configuration
• <subsiteName> is the subsite the template will be used on (passed to the worker by the Authentication template as part of the call to renderLoginForm). This must match the subsite "Name" in your Subsite Properties. This name is case sensitive
• <typeName> is the provider type you want to override (eg facebook, google, adfs). All named providers of this type will use the override unless a specific <providerName> override is found first. Enter this name in lowercase
• <providerName> a named provider in your worker configuration (eg you have configured two providers of the Facebook type with different names). Enter this name in lowercase

You'll need to resend the configuration to the API Server if you create new files and directories, even with caching disabled. Once the templates have been created, editing them with the cache disabled will display your changes straight away. Similarly, you'll need to resend the configuration if you delete a file or directory.

Re-enable the hbCacheTemplates when you have finished.

Example Override Tree

This example overrides the openid templates on the GOSSDocs subsite, and globally overrides (ie all named providers across all subsites) the adfs templates:

Creating an Override Template for a Subsite

To create an override for a subsite, do the following.

1. Create the override root as described above
2. In the "named" directory create a directory with the name of your subsite - GOSSDocs in the example above
3. In the subsite directory create a directory called "types"
4. In the types directory create a directory for the provider - openid in the example above. The name needs to match the system name described in the Provider Types documentation of each provider
5. Right-click on your provider directory and choose "Create a file"
6. In the editor, create your template with the appropriate name and .hbs extension

Default Templates

This zip file contains all of the default templates (in the types directory): Default Auth Handlebars Templates (ZIP, 62KB)

You could import the entire directory into the custom folder, but we recommend only copying in the files you need.

If you create overrides you will need to maintain them if we release updates.

Context

The data object passed to your template includes all of the worker and provider configuration, which you can access via the this object.

Base Provider Parameters can be accessed by name, for example {{this.providerDisplayName}}. Provider specific values are nested in the params object, for example in the iCMSiteUser provider, you could access {{this.params.lockoutThreshold}}.

{{buttonLabel}} is made up of the labelPrefix (which default to "Log in with") plus the provider display name.