Themes

Form Fields

Id Optional

An optional UUID. When this value is omitted a unique Id will be generated automatically.

Name Required

A unique name to identity the theme. This name is for display purposes only and it can be modified later if desired.

Templates

Stylesheet (CSS) Optional

This CSS stylesheet may be used to style the themed pages.

This CSS will be included in the head tag in the Helpers head macro. You may also choose to include other remote stylesheets by using the <style> tag within the head macro.

<style>
  ${theme.stylesheet()}
</style>

Messages Optional

This section allows you to add additional localized messages to your theme. When creating an additional locale it is not required that all messages are defined for each language. If a message key is not defined for the specified locale, the value from the default bundles will be used.

If you intend to localize your login templates, you may find our community contributed and maintained messages in our GitHub repository. https://github.com/FusionAuth/fusionauth-localization

Helpers Required

This template contains all of the main helper macros to define the head, body and footer. To begin theming FusionAuth you’ll want to start with this template as it will affect all other templates.

See Helpers section below for additional information.

Email verification complete Required

This page is used after a user has verified their email address by clicking the URL in the email. After FusionAuth has updated their user object to indicate that their email was verified, the browser is redirected to this page.

/email/complete

Email verification re-send Required

This page is used after a user has asked for the verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.

/email/send

Email verification Required

This page is rendered when a user clicks the URL from the verification email and the verificationId has expired. FusionAuth expires verificationId after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.

/email/verify

OAuth authorize Required

This is the main login page for FusionAuth and is used for all interactive OAuth2 and OpenID Connect workflows.

/oauth2/authorize

OAuth child registration not allowed Required

This page contains a form where a child must provide their parent’s email address to ask their parent to create an account for them in a Consent workflow.

/oauth2/child-registration-not-allowed

OAuth child registration not allowed complete Required

This page is rendered is rendered after a child provides their parent’s email address for parental consent in a Consent workflow.

/oauth2/child-registration-not-allowed-complete

OAuth complete registration Required

This page contains a form that is used for users that have accounts but might be missing required fields.

/oauth2/complete-registration

OAuth device Required Since 1.11.0

This page contains a form for accepting an end user’s short code for the interactive portion of the OAuth Device Authorization Grant workflow.

/oauth2/device

OAuth device complete Required Since 1.12.0

This page contains a complete message indicating the device authentication has completed.

/oauth2/device-complete

OAuth error Required

This page is used if the user starts or is in the middle of the OAuth workflow and any type of error occurs. This could be caused by the user messing with the URL or internally some type of information wasn’t passed between the OAuth endpoints correctly. For example, if you are federating login to an external IdP and that IdP does not properly echo the state parameter, FusionAuth’s OAuth workflow will break and this page will be displayed.

/oauth2/error

OAuth logout Required

This page is used if the user initiates an OAuth logout. This page causes the user to be logged out of all associated applications via a front-channel mechanism before being redirected.

/oauth2/logout

OAuth passwordless Required

This page is rendered when the user starts the passwordless login workflow. The page renders the form where the user types in their email address.

/oauth2/passwordless

OAuth register Required

This page is used to register the user for the application.

/oauth2/register

OAuth two-factor Required

This page is used if the user has two-factor authentication enabled and they need to type in their code again. FusionAuth will properly handle the SMS or authenticator app processing on the back end. This page contains the form that the user will put their code into.

/oauth2/two-factor

OAuth wait Required Since 1.12.0

This page is rendered when FusionAuth is waiting for an external provided to complete an out of band authentication request. For example, during a HYPR login this page will be displayed until the user completes authentication.

/oauth2/wait

OAuth Change password form Required

This page is used if the user is required to change their password or if they have requested a password reset. This page contains the form that allows the user to provide a new password.

/password/change

OAuth password complete Required

This page is used after the user has successfully updated their password (or reset it). This page should instruct the user that their password was updated and that they need to login again.

/password/complete

Forgot password Required

This page is used when a user starts the forgot password workflow. This page renders the form where the user types in their email address.

/password/forgot

Forgot password sent Required

This page is used when a user has submitted the forgot password form with their email. FusionAuth does not indicate back to the user if their email address was valid in order to prevent malicious activity that could reveal valid email addresses. Therefore, this page should indicate to the user that if their email was valid, they will receive an email shortly with a link to reset their password.

/password/sent

SAML logout Required

Since 1.25.0:: This page is used if the user initiates a SAML logout. This page causes the user to be logged out of all associated applications via a front-channel mechanism before being redirected.

/samlv2/logout

Verify registration complete Required

This page is used after a user has verified their email address for a specific application (i.e. a user registration) by clicking the URL in the email. After FusionAuth has updated their registration object to indicate that their email was verified, the browser is redirected to this page.

/registration/complete

Verify registration send Required

This page is used after a user has asked for the application specific verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.

/registration/send

Verify registration Required

This page is used when a user clicks the URL from the application specific verification email and the verificationId has expired. FusionAuth expires verificationId after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.

/registration/verify

Section Helpers

• html

  • Renders the <html> element

• head

  • Renders the <head> element and everything inside it including the <title>, CSS, Java Script, and meta information

• body

  • Renders the <body> element

• header

  • Renders any type of header for each page. This could be a navigation bar, side bar, or page details

• main

  • Renders the main content body of each page. If all of your pages will have similar HTML elements like a container, this is the place to put them.

• footer

  • Renders the footer content of each page. This might contain links, nav, privacy policies, etc.

Here is an example of what one of these helpers looks like:

[#macro html]
<!DOCTYPE html>
<html>
  [#nested/]
</html>
[/#macro]

The key to these macros is the [#nested/] element. This is the location that FreeMarker will insert any nested content when you use the macro. Here is an example of using this macro:

[@helpers.html]
<body>
Hello world!
</body>
[/@helpers.html]

Everything inside the macro will be place where the [#nested/] element is. Therefore, the result of our example would be this HTML:

<!DOCTYPE html>
<html>
<body>
Hello world!
</body>
</html>

All of the page templates use these macros, which makes it much easier to style all of the pages at one time. You simply edit the macros and your changes will take effect on all of the pages listed above.

Social (alternative) Login Helpers

In addition to the section helpers, the _helpers.ftl template also contains a few additional macros that can be used to setup social and alternative logins. Currently, FusionAuth supports these social login providers:

• Facebook

• Google

• Twitter

• Generic OpenID Connect

• Generic SAML v2

Once you have configured your alternative logins (called identity providers in the interface and API), they will appear on the FusionAuth stock login form. This is because our stock login form includes this code:

[@helpers.head]
  [@helpers.alternativeLoginsScript clientId=client_id identityProviders=identityProviders/]
  ...
[/@helpers.head]

[@helpers.body]
  ...

  [@helpers.alternativeLogins clientId=client_id identityProviders=identityProviders/]
[/@helpers.body]

The first macro (alternativeLoginScripts) includes the JavaScript libraries that FusionAuth uses to hook up the identity providers. Unless you want to write your own JavaScript or use a third-party library, you will need this JavaScript in the <head> tag in order for FusionAuth to leverage external login providers.

The second macro (alternativeLogins) produces the login buttons for each of the configured identity providers. These buttons are all hooked up to the JavaScript included in the <head> of the page in order to make it all work nicely.

You might want to use your own buttons for social logins. This is possible with FusionAuth, but you will need to do a couple of things to make it all work.

First, you need to remove the [@helpers.alternativeLogins] macro call.

Second, you need to use a specific id or class on your HTML element for the button. Here are the id s or class es for each identity provider:

• id="google-login-button" is used for Google

• id="facebook-login-button" is used for Facebook

• id="twitter-login-button" is used for Twitter

• class="openid login-button" is used for Generic OpenID Connect

• class="samlv2 login-button" is used for Generic SAML v2

And finally, you need to ensure that Prime.js is included on your page. This library ships with FusionAuth and you just need to ensure it is included like this:

<script src="/js/prime-min.js"></script>

Alert and Error Helpers

The _helpers.ftl template also provides a couple of macros that can be used to output errors and alerts that might occur. The best bet is to include these macros in your main macro. Here are the macros and their purpose:

• printErrorAlerts

  • This outputs any error alerts. These are normally displayed at the top of the page and you might want to make them able to be dismiss (i.e. removed from the page).

• printInfoAlerts

  • This outputs any informational alerts. These are the same as the errors, but might have different CSS.

• alert

  • This macro is used by the printErrorAlerts and printInfoAlerts but you can also use it directly to display an error or info message anywhere on the page.

Form Helpers

The _helpers.ftl template also provides a couple of macros that help render form elements and output form errors. Here are the macros you can use:

• hidden

  • This outputs a hidden input element. Many pieces of the OAuth workflow and the other pages in FusionAuth use hidden form fields to store data. This macro uses the eval feature of FreeMarker in order to pull in data that was in the request. You shouldn’t edit this macro unless you know what you are doing.

• input

  • This outputs an input element plus a label and any errors that might have occurred on the form field. You can use this for text, passwords, and other input elements. FusionAuth also leverages addons which are icons next to the input field that provide visual cues to the user. This macro allows you to leverage addons as well. Similar to the hidden element, you should not edit this unless you know what you are doing.

• errors

  • This macro is used by the input macro to render errors on the field. You can use this if you write your own input macros. Otherwise, you likely won’t use this.

• button

  • This macro renders a button that can be used to submit a form. The FusionAuth version of this macro includes an icon and the button text.

Previewing a theme

If you want to see how your theme works, you can always open a browser with no active FusionAuth session and visit the hosted login pages.

However, at times, you may need to make changes in your theme that you want to view without going through an entire registration process. You can easily do so by previewing the theme via the administrative user interface.

Navigate to Customizations → Themes. Choose your theme, then click the preview link (the green magnifying glass):

This will open a new tab. Click on any of the pages you’ve modifed in the left hand navigation, for example OAuth register, and you’ll see the page as it would be rendered.

Example of Customizing the Authorize Page

Now that you have a good overview of all the templates, macros and helpers, here is an example of customizing the Authorize page.

Let’s assume you want to change the header and footer across all of the pages including the Authorize page. This is accomplished by editing the helpers.header and helpers.footer macros. For the header, let’s assume you want to add a Sign Up and Login link. For the footer, let’s assume you want to add a link to your privacy policy. Here are the macros that include these new links:

[#macro header]
  <header class="my-custom-header">
    <nav>
      <ul>
        <li class="login"><a target="_blank" href="https://my-application.com/login">Login</li>
        <li class="sign-up"><a target="_blank" href="https://my-application.com/sign-up">Sign Up</li>
      </ul>
    </nav>
  </header>

  [#nested/]
[/#macro]

[#macro footer]
  <footer class="my-custom-footer">
    <nav>
      <ul>
        <li class="privacy-policy"><a target="_blank" href="https://my-application.com/privacy-policy">Privacy Policy</li>
      </ul>
    </nav>
  </footer>

  [#nested/]
[/#macro]

Once you make these changes, they will take effect on all of the pages listed above.

Common Variables

Email verification complete

No page specific variables.

Email verification re-send

Email verification

OAuth Authorize

OAuth child registration not allowed

OAuth child registration not allowed complete

No page specific variables.

OAuth complete registration

No page specific variables.

OAuth device

OAuth device complete

OAuth error

OAuth logout

OAuth passwordless

OAuth register

OAuth two-factor

OAuth wait

Change password form

Change password complete

No page specific variables.

Forgot password

No page specific variables.

Forgot password sent

No page specific variables.

SAML logout

OAuth complete registration

No page specific variables.

Verify registration re-send

Verify registration

Templates

When new functionality is introduced to the hosted login pages, new theme templates are occasionally added. They are added to the default theme by the upgrade process, but if you’ve customized your theme to fit your brand, you’ll need to modify the theme to have the new template.

In the version release notes, any new templates are documented. This will tell you that you’ll want to take a closer look at the themes post upgrade.

As part of your upgrade testing, open the administrative user interface and navigate to Customizations > Themes.

If any themes are missing templates, they will show as "Upgrade Required". Port the new theme files over to your custom theme, modify them as needed, and save the theme.

Messages

When new functionality is introduced to the hosted login pages, new theme message keys are sometimes required. They are added to the default theme messages file by the upgrade process.

However, if you have customized your theme, the new keys are not added to that modified theme. The first time you try to modify your theme, you’ll receive an error message similar to the text below:

Missing required keys. See text area below for default English translations. To continue, please copy the values from below into the Messages text area.

FusionAuth warns you about missing required keys in order to avoid an inadvertent bad user experience. The default display for keys with no valid values in theme Messages is the key text, such as [ExternalAuthenticationException]LinkedInToken, which can be confusing for end users.

During an upgrade, you can find these keys by testing the upgrade on a development instance or comparing releases in the fusionauth-localization repo. You can safely add these new key values to your theme prior to an upgrade. Any unused messages in a theme’s messages file are silently ignored (unless malformed).

The extra lines won’t do any harm, and will ensure an excellent end user experience if they stumble on new functionality right after an upgrade.