Broadleaf Microservices
  • v1.0.0-latest-prod

Customizing Frontend Templates

Overview

Here, we will go over how to customize the Auth frontend templates. The frontend runs via a Spring MVC app using Thymeleaf as the template engine. This should be provided as AuthenticationServicesImage.

Important
 The default templates and styles are bundled with the main auth service JARs.

Customizing Templates

Custom templates for authentication pages may be defined by placing templates in src/main/resources/templates of your copy of AuthenticationServicesImage. Additionally, any templates specific to a particular AuthorizationServer should be added in the appropriate subdirectory of /templates such as /templates/admin. No additional code configuration is required when using custom templates.

However, if there are any overrides specific to an AuthorizationServer, it must have its templatePath property set to the correct path. Thus, for example the admin AuthorizationSever#templatePath is set to admin.

Tip

An authorization server is responsible for authenticating users. Generally, there are at least two authorization servers per tenant: one for customer users and one for admin users. The frontend templates are thus able to be set per authorization server.

Default Templates

There are several HTML files that must be defined in the root of the templatePath directory:

  1. login.html

    • Standard login page

  2. request-password-reset.html

    • The password reset request form.

  3. sent-reset-password.html

    • Confirmation page that a password reset request has been sent.

  4. reset-password.html

    • The reset password form, triggered via a password reset e-mail.

  5. reset-password-success.html

    • Confirmation page that a password was successfully reset.

  6. change-password.html

    • User initiated change password form

  7. change-password-success.html

    • Confirmation page that a user initiated password change was successful.

Additionally, there are partial or fragment templates such as head.html and primary-button.html for commonly shared parts of the main templates. Overrides for these should be placed in /templates/fragments.

Tip
 All the default templates and styles are included in the JARs. You can use your IDE of choice to examine them in resources/blctemplates for templates and resources/static for CSS and JS.

Customizing Styles

Custom styles just need to be on the classpath such as resources/static/css. The default stylesheet is included in the source JARs for AuthenticationServices. To include it and add custom stylesheets, you should override head.html like the following:

templates/fragments/head.html
<th:block xmlns="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org">
    <head th:fragment="head(title)">
        <title th:utext="#{${title}}"></title>
        <meta charset="utf-8"/>
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>

        <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport"/>
        <meta name="viewport" content="width=device-width"/>
        <link rel="shortcut icon" type="image/x-icon" th:href="@{/favicon.ico}"/>
        <!-- default stylesheet -->
        <link rel="stylesheet" type="text/css" th:href="@{/static/css/styles.min.css}"/>
        <!-- followed by custom stylesheet(s) -->
        <link rel="stylesheet" type="text/css" th:href="@{/static/css/custom-styles.css}"/>
    </head>
</th:block>

Custom Template Resolvers

If you wish to define a custom template resolver, register a Spring Bean of type org.thymeleaf.spring5.templateresolver.SpringResourceTemplateResolver with the desired behavior. To override existing template resolvers, set SpringResourceTemplateResolver#order to a value less than or equal to zero.

Custom error message on login failure

The login failure page has the following parameters that control the look of the error page:

Table 1. Default Login Failure URL parameters

Parameter

Description

error

Shows a red error box

errorCode

Controls the error message to be displayed

username

If supplied, will automatically fill in the username field on the login form

Out of box, the following error message codes exist:

Table 2. Default Error messages

Error code

Description

login.error.invalid-login

Generic login failure message. This is the default error message on a failed login and no errorCode parameter is supplied.

login.error.user-inactive

Shown when a user is marked as inactive (is_active='N' in the database)

Error codes are shown on the login form depending on the errorCode url parameter. Consider the URL /login?error=true&errorCode=login.error.user-inactive&client_id=heatclinic&username=myuser@gmail.com

This results in the following on the login page:

Login Error Example

Custom login redirect URLs

Out of box, the only way to pass custom parameters to the failed login attempt page is via redirect URL parameters. Redirect URIs can be set based on the exception that’s thrown.

Customizing the messaging of the login page on login failure is achieved through URL parameters. This redirect URL may be customized with exception mappings. For example, the inactive user message appears when a UserNotActiveException is thrown.

To define a custom redirect URI with custom parameters, define a custom Spring bean of the type com.broadleafcommerce.auth.security.web.authentication.AuthenticationFailureExceptionMapping.

For example:

@Bean
public AuthenticationFailureExceptionMapping myAuthenticationFailureMapping() {
  return new AuthenticationFailureExceptionMapping(UserNotFoundException.class, "/login?error=true&errorCode=login.error.user-not-found");
}