The Authentication worker uses Handlebars templates to generate the HTML used in site login forms, account management pages 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
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
Generic Actions
These actions include the templates used for account management, mismatched (update prompt) email messages, user consent, 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\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
Default Template Tree
This is a simplified view (it doesn't include all of the actions or all of the types) of the standard template tree found in the main auth directory.
Overrides
Overrides let you customise the templates used by the worker. Your overrides are stored in the
The files you want to customise must have the same names as those being overridden. Their position in the tree determines how they are used.
While developing your override templates, set the worker's
Example Override Tree
This example globally overrides the login form and user consent templates, and overrides the body template and consent templates for all providers of the the Facebook type on a named subsite.
In most cases, if all you want to do is override the body.hbs template of all providers of a given type on a named subsite (eg customise the iCMSiteUser login template on your intranet), create your new template in <overrideRoot>\named\<subsiteName>\types\<typeName>\body.hbs
Template Resolution
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> in our standard Authentication template the name of the subsite making the call to
renderLoginForm is passed as the value ofnamedTemplateOverrides , so name your directories in the overrideRoot after subsites - <typeName> is the provider type you want to override. All named providers of this type will use the override unless a specific <providerName> override is found first
- <providerName> a named provider in your worker configuration of one of the base types (eg you have configured two providers of the Facebook type with different names)
| Path | Type | Description |
|---|---|---|
| Top Level | ||
| <overrideRoot>\named\ <subsite>\loginform\ | NamedOverride | I want to override the login form for a named subsite |
| <overrideRoot>\loginform\ | Global | I want to override the login form globally |
| templates\loginform\ | Type | The default, as supplied with the worker |
| Type Specific | ||
| <overrideRoot>\named\ <subsite>\<providerName>\types\<typeName> | NamedOverride + Provider | I want to override the template for a named provider of this type on a specific subsite |
| <overrideRoot>\named\ <subsite>\types\<typeName>\ | NamedOverride | I want to override the template for all providers of this type on this subsite |
| <overrideRoot>\ <providerName>\types\<typeName>\ | Provider | I want to override the template for a named provider of this type, whatever subsite it is used on |
| <overrideRoot>\types\<typeName>\ | Global | I want to override the template for all providers of this type |
| templates\types\<typeName>\ | Type | The default, as supplied with the worker |
| Actions | ||
| <overrideRoot>\named\ <subsite>\<typeName>\actions\ | NamedOverride + Provider | I want to override the action template for all providers of this type using this action on a certain subsite |
| <overrideRoot>\named\ <subsite>\actions\ | NamedOverride | I want to override the action template for all providers using this action on a certain subsite |
| <overrideRoot>\<typeName>\actions\ | Provider | I want to override the action template for all providers of this type type using this action |
| <overrideRoot>\actions\ | Global | I want to override the action template for all providers using this action |
| templates\actions\ | Type | The default, as supplied with the worker |
Model
The following elements are available to use in your templates.
| Name | Type | Description |
|---|---|---|
| actionUrl | String | Form submission action URL |
| code | String | The two-factor authentication code |
| provider | Object | The base provider properties, eg provider.providerDisplayName |
| provider.hbHeaderTemplatePath | String | Path to the provider's header template. Passed to the |
| provider.hbBodyTemplatePath | String | Path to the provider's body template. Passed to the |
| provider.params | Object | Provider parameters taken from the settings in the worker configuration |
| type | TypeBase | The type's TypeBase subclass. toString() prints the value of authType, eg "saml2" |
| authType | AuthType (enum) | Enum stating the auth type, eg "saml2" |
| authSession | Object | All of the properties in the current Auth Sessions |
| workerConfig | Object | Any worker.conf property |
Share this page
