Theme Template Variables
Overview
Template variables are provided to allow intelligent customization of theme templates. You can use Freemarker to display, hide, or otherwise logically modify what your end users sees based on these values.
Each template has different variables that are available to it. These variables can be used in the template to help with rendering the HTML. There are also a couple of common variables that are available in all of the pages. The common variables and the page specific variables are all listed below.
When the variable is FusionAuth specific, such as the tenant or application, the fields of the variable are the same as the JSON object described in the Retrieve section of the corresponding API documentation.
By default FusionAuth will provide HTML escaping on all values rendered in HTML, this protects you from script injection attacks. If you find a value that is being incorrectly escaped you may need to utilize the FreeMarker built in for no-escape ?no_esc.
Common Variables
The application resolved by the provided client_id provided on the request. If the request was made without a client_id then this variable will be undefined. Ensure you reference it using a null safe strategy if you are using some of the themed pages without a client_id.
See the Application API for details on this object.
The OAuth v2.0 client_id parameter. This is synonymous with FusionAuth’s Application Id.
When there is an active SSO session, this variable will contain the currently logged in user. When an SSO session does not yet exist, this variable will be null. If the user has not checked the Keep me signed in option, there is no SSO session and this variable will be null.
See the User API for details on this object.
A list of error messages that were generated during the processing of the request.
A map of field messages (usually errors) that were generated during the processing of the request. The key into the map is the name of the form field and the value is a list that contains the errors for that form field.
The locale used to localize messages.
You can find the JavaDoc for this object available here: https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html
The HttpServletRequest object that is part of the Java Servlet specification.
You can find the JavaDoc for this object available here: https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html
The tenant that has been resolved for this template. This value has either been specified on the request by providing the tenantId request parameter or it has been resolved by other request parameters such as the client_id.
If you need to customize the look and feel for different tenants but desire to use the same theme to lower maintenance, store values in tenant.data. For example, you could set tenant.data.customElements.buttonText and tenant.data.customElements.buttonColor, then retrieve values off these fields in the theme templates.
See the Tenant API for details on this object.
The unique Tenant identifier, this is equivalent to tenant.id.
The theme that has been resolved for this template. This could be resolved based on the tenant or the application.
See the Themes API for details on this object.
The unique Theme identifier, this is equivalent to theme.id.
Template Specific Variables
In addition to the common variables documented above, each template may have additional variables available to that only make sense in the context of this template. For example, the OAuth Authorize page (the login page) can access the loginId template variable, but this variable would make no sense on the email verification template.
Account edit
URI
Variables
The User fields to display in the form. Each key maps to form fields by section within a Self-Service User form.
The User object corresponding to the authenticated user.
Account index
URI
Variables
A boolean that indicates if a Self-Service User form has been configured for this application.
A boolean that indicates if any multi-factor authentication methods have been enabled on the tenant.
The User object corresponding to the authenticated user.
A boolean that indicates if WebAuthn has been enabled on the tenant.
Account two-factor disable
URI
Variables
The email address you are attempting to disable, this will be available when the method is email.
The two-factor method you are disabling. The possible values are:
authenticatoremailsms
The actual Id of the two-factor method you are disabling.
The mobile phone you are attempting to disable, this will be available when the method is sms.
The User object corresponding to the authenticated user.
Account two-factor enable
URI
Variables
The two-factor methods that are available to be configured.
The email address if the method value is email.
The two-factor method. The possible values are:
authenticatoremailsms
The mobile phone if the method is sms.
The recovery codes when a user configured multi-factor authentication for the first time. This will be available after a method has been successfully enabled and this template is rendered a second time. If you already have one method enabled, the recovery codes will not be displayed.
A Base64 encoded secret for the authenticator method.
A Base32 encoded form of the provided secret for the authenticator method.
The User object corresponding to the authenticated user.
Account two-factor index
URI
Variables
The User object corresponding to the authenticated user.
Account add WebAuthn passkey
URI
Variables
The User object corresponding to the authenticated user.
Account delete WebAuthn passkey
URI
Variables
The WebAuthn passkey the user is deleting. See the link:/docs/v1/tech/apis/webauthn[WebAuthn API] for details on this object.
Account WebAuthn index
URI
Variables
The list of registered WebAuthn passkeys for the current user. See the link:/docs/v1/tech/apis/webauthn[WebAuthn API] for details on this object.
Email verification complete
URI
Email verification re-sent
URI
Variables
The email address that was passed as a URL parameter. This is the email address that is requesting that the verification email be re-sent to.
A boolean that indicates if the verification email was re-sent or not.
Email verification required
URI
Variables
When true, an additional form is displayed to allow the user to update their email address. This is intended to assist the user if they mis-typed their email address previously. This occurs when Allow email change when gated is enabled under email verification settings on the Tenant.
When true, a form input is displayed to allow a user to enter the verification code. This occurs when Verification strategy is set to FormField under email verification settings on the Tenant.
The current value of the user's email address. This may be useful to indicate to the user which email address was sent a verification code.
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
The verification Id that was included on as a URL parameter. This is the high entropy value that will be paired with the low entropy one time code to complete email verification.
Email verification
URI
Variables
Defaults to true on this page.
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
The verification Id that was included on as a URL parameter but was invalid. This page does a redirect if the verificationId is valid.
Index
URI
OAuth authorize
URI
Variables
A boolean that indicates if the WebAuthn bootstrap workflow is enabled for the current application.
The OAuth v2.0 code_challenge parameter.
The OAuth v2.0 code_challenge_method parameter used in conjunction with PKCE. Can be either plain or S256.
The PendingIdpLink that is generated when using the device OAuth flow. This object provides information about the current state of the user and the identity provider prior to completing the link. This is available when linking or registering a device ( i.e. Playstation or XBox).
A human readable name for this link to help you identify this link. This value will generally be an email address, or username.
The email address of the FusionAuth user being linked to the identity provider.
See the link:/docs/v1/tech/apis/identity-providers/links[Link API] for details on this object.
The name of the identity provider that is being linked to.
The type of identity provider that is being linked to.
The Id for the User that is provided by the identity provider.
A boolean that indicates if a user has exceeded the maximum number of links allowed.
The FusionAuth user that is linked to the identity provider.
The username of the FusionAuth user being linked to the identity provider.
A boolean that indicates if there are domain-based identity providers configured. These identity providers use the user's email address to determine if an external IdP should be used to log the user in.
A map of the configured identity providers for the Application the user is logging into. The key into the map is the type of the identity provider (i.e. Facebook or OpenIDConnect). The value is a list of all of the configured identity providers for that type.
+
NOTE: This map does not contain any "domain-based" identity providers since those are handled differently using just the Email input field to start and then possibly redirecting the browser to the external IdP login page.
The value from the loginId form field. This is either the username or the email of the user attempting to log into FusionAuth.
Metadata on when the JWT Refresh Token was created
The OpenID Connect nonce request parameter.
A boolean that controls whether or not to to utilize a passwordless flow.
This is the unique value when creating a link between a unique UUID returned by the IdP and a new or existing FusionAuth user.
A human readable name for this link to help you identify this link. This value will generally be an email address, or username.
The email address of the FusionAuth user being linked to the identity provider.
See the link:/docs/v1/tech/apis/identity-providers/links[Link API] for details on this object.
The name of the identity provider that is being linked to.
The type of identity provider that is being linked to.
The Id for the User that is provided by the identity provider.
A boolean that indicates if a user has exceeded the maximum number of links allowed.
The FusionAuth user that is linked to the identity provider.
The username of the FusionAuth user being linked to the identity provider.
The OAuth v2.0 redirect_uri parameter. This is the URI that FusionAuth will redirect the user to once they have successfully logged in.
This value is used to record if ths user would like to have their device remembered on the next login.
The OAuth v2.0 response_type parameter.
The OAuth v2.0 scope parameter.
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
A boolean that controls whether the password field is shown if there are domain-based identity providers. If there are domain based identity providers and the user types in an email address that is not managed by the identity provider, FusionAuth will then re-render this template with this variable set to true. This will indicate that the password field should be shown so that the user can complete their login.
If you need an example of this behavior, check out the login page at https://www.pivotaltracker.com/signin.
A boolean that indicates if the WebAuthn re-authentication workflow is enabled for the current application, and there are re-authentication passkeys available on the current device.
The OAuth v2.0 state parameter.
The timezone that the user is in. This is normally guessed by the timezone JavaScript library (or something similar) and then stored in a hidden input field on the login form.
The user code provided by the user in the form, or if the user_code was provided on the URL using a request parameter such as ?user_code=123 this value will be provided in the template using this variable.
The version.
OAuth authorized not registered
URI
OAuth child registration not allowed
URI
Variables
The parent’s email address provided in the input field of the form.
OAuth child registration not allowed complete
URI
OAuth complete registration
URI
OAuth device
URI
Variables
The PendingIdpLink that is generated when using the device OAuth flow. This object provides information about the current state of the user and the identity provider prior to completing the link. This is available when linking or registering a device ( i.e. Playstation or XBox).
A human readable name for this link to help you identify this link. This value will generally be an email address, or username.
The email address of the FusionAuth user being linked to the identity provider.
See the link:/docs/v1/tech/apis/identity-providers/links[Link API] for details on this object.
The name of the identity provider that is being linked to.
The type of identity provider that is being linked to.
The Id for the User that is provided by the identity provider.
A boolean that indicates if a user has exceeded the maximum number of links allowed.
The FusionAuth user that is linked to the identity provider.
The username of the FusionAuth user being linked to the identity provider.
The user code provided by the user in the form, or if the user_code was provided on the URL using a request parameter such as ?user_code=123 this value will be provided in the template using this variable.
The length of the interactive user code. This value may be used to build the correct number of input fields for the interactive code.
OAuth device complete
URI
Variables
An optional parameter that may be present if the completion of this device request resulted in one or more Identity Provider links being established to this user. + This variable may be helpful if you wish to communicate to the user which links have been completed.
OAuth error
URI
Variables
The OAuth error JSON that could be helpful for developers while debugging.
OAuth logout
URI
Variables
A set of URLs associated with all of the applications in the tenant to log out the user.
The URL to be redirected to after the front-channel logout occur.
A set of URLs associated with all of the applications the user is registered for to log out the user.
OAuth passwordless
URI
Variables
The OAuth v2.0 redirect_uri parameter. This is the URI that FusionAuth will redirect the user to once they have successfully logged in.
The OAuth v2.0 response_type parameter.
The OAuth v2.0 scope parameter.
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
The OAuth v2.0 state parameter.
The timezone that the user is in. This is normally guessed by the timezone JavaScript library (or something similar) and then stored in a hidden input field on the login form.
OAuth register
URI
Variables
Whether or not to collect a birth date for a Consent workflow.
Whether or not to render a hidden field for passing along the birthdate in the form.
Whether or not a parent's email address is required for a Consent Workflow.
An object that contains the password validation rules. The object fields are defined in keys to this object, as defined below.
The maximum length of a password.
The minimum length of a password.
The number of previous passwords the user is not allowed to re-use.
Whether or not the user must use upper and lower-cased letter.
Whether or not the user must use at least one non-alphabetic character in their password.
Whether or not the user must use at least one numeric character in their password.
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
OAuth start IdP link
URI
Variables
The PendingIdpLink that is generated when using the device OAuth flow. This object provides information about the current state of the user and the identity provider prior to completing the link. This is available when linking or registering a device ( i.e. Playstation or XBox).
A human readable name for this link to help you identify this link. This value will generally be an email address, or username.
The email address of the FusionAuth user being linked to the identity provider.
See the link:/docs/v1/tech/apis/identity-providers/links[Link API] for details on this object.
The name of the identity provider that is being linked to.
The type of identity provider that is being linked to.
The Id for the User that is provided by the identity provider.
A boolean that indicates if a user has exceeded the maximum number of links allowed.
The FusionAuth user that is linked to the identity provider.
The username of the FusionAuth user being linked to the identity provider.
This is the unique value when creating a link between a unique UUID returned by the IdP and a new or existing FusionAuth user.
A human readable name for this link to help you identify this link. This value will generally be an email address, or username.
The email address of the FusionAuth user being linked to the identity provider.
See the link:/docs/v1/tech/apis/identity-providers/links[Link API] for details on this object.
The name of the identity provider that is being linked to.
The type of identity provider that is being linked to.
The Id for the User that is provided by the identity provider.
A boolean that indicates if a user has exceeded the maximum number of links allowed.
The FusionAuth user that is linked to the identity provider.
The username of the FusionAuth user being linked to the identity provider.
A boolean that indicates if the application is configured for self registration.
OAuth two-factor
URI
Variables
The value of the code form field on the page. This will be available only after the user has submitted the form.
The currently selected two-factor method. This may be helpful if you want to communicate to the end user their currently selected method.
+
For example, method.method will indicate the type of method, authenticator, email or sms. Based upon the method, the method.email or method.mobilePhone will indicate which transport is being used to send the user a code.
The method Id. This Id, if defined, will represent the currently selected method, or last used method.
Whether or not FusionAuth has pushed (SMS) enabled for two-factor.
Removed in version 1.26.0
Whether or not the user prefers push (SMS) for two-factor.
Removed in version 1.26.0
The OAuth v2.0 redirect_uri parameter. This is the URI that FusionAuth will redirect the user to once they have successfully logged in.
Whether or not the user wants the code to be resent to their phone (valid for push two-factor).
Removed in version 1.26.0
The OAuth v2.0 response_type parameter.
The OAuth v2.0 scope parameter.
Whether or not to display a link to allow the user to select a different method or resend the code. This value will be true when more than one option exist for the user to select, or the available method is email or sms which will allow for a resend option.
The OAuth v2.0 state parameter.
The timezone that the user is in. This is normally guessed by the timezone JavaScript library (or something similar) and then stored in a hidden input field on the login form.
The value of the "Trust this computer" form field. This will be available only after the user has submitted the form. Otherwise, it defaults to false. When the user checks this box, a cookie is dropped so that two-factor authentication can be skipped on this computer.
The unique Id of the current multi-factor authentication attempt.
Whether or not the user is capable of receiving push notifications for two-factor. This means that the user has a mobile phone number.
Removed in version 1.26.0
OAuth two-factor enable
URI
Variables
The two-factor methods that are available to be configured.
Returned when twoFactorId is provided to complete Two Factor login.
The email address if the method value is email.
The two-factor method. The possible values are:
authenticatoremailsms
The mobile phone if the method is sms.
A base64 encoded version of the secret that can be used to build a QR code when using the authenticator method.
A base32 encoded version of the secret that can be used to build a QR code when using the authenticator method.
OAuth two-factor enable complete
URI
Variables
The recovery codes when a user configured multi-factor authentication for the first time. This will be available after a method has been successfully enabled and this template is rendered a second time. If you already have a method enabled, the recovery codes will not be displayed.
OAuth two-factor methods
URI
Variables
A map of two-factor methods that the user has configured. The key into the map is the unique methodId. The value is the two-factor method.
The method Id. This Id, if defined, will represent the currently selected method, or last used method.
The total number of recovery codes that the user has available to use.
The timezone that the user is in. This is normally guessed by the timezone JavaScript library (or something similar) and then stored in a hidden input field on the login form.
The unique Id of the current multi-factor authentication attempt.
OAuth wait
URI
Variables
The FusionAuth temporary code used to complete this external authentication request.
OAuth WebAuthn
URI
Variables
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
OAuth WebAuthn Reauth
URI
Variables
A list of the WebAuthn passkeys available to complete re-authentication on the current device. See the link:/docs/v1/tech/apis/webauthn[WebAuthn API] for details on this object.
OAuth WebAuthn Reauth Enable
URI
Variables
A list of the current user's registered WebAuthn passkeys that may be suitable for use in the re-authentication workflow. See the link:/docs/v1/tech/apis/webauthn[WebAuthn API] for details on this object.
OAuth Change password form
URI
Variables
The id that was sent to the user (usually via email) that allows them to change their password. Normally, this id is included in the email template for the forgot password workflow and when the user clicks the link in the email, they are taken to this page with this parameter on the URL.
An object that contains the password validation rules. The object fields are defined in keys to this object, as defined below.
The maximum length of a password.
The minimum length of a password.
The number of previous passwords the user is not allowed to re-use.
Whether or not the user must use upper and lower-cased letter.
Whether or not the user must use at least one non-alphabetic character in their password.
Whether or not the user must use at least one numeric character in their password.
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
OAuth password complete
URI
Forgot password
URI
Variables
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
Forgot password sent
URI
Verify registration complete
URI
Verify registration re-sent
URI
Variables
The Id of the application that the user is verifying their email for and needs the email to be resent.
The email address that was passed as a URL parameter. This is the email address that is requesting that the verification email be re-sent to.
A boolean that indicates if the verification email was re-sent or not.
Verify registration required
URI
Variables
When true, a form input is displayed to allow a user to enter the verification code. This occurs when Verification strategy is set to FormField under registration verification settings on the Application.
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
The verification Id that was included on as a URL parameter. This is the high entropy value that will be paired with the low entropy one time code to complete email verification.
Verify registration
URI
Variables
A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).
The verification id that was included on as a URL parameter but was invalid. This page does a redirect if the verificationId is valid.
SAML logout
URI
Variables
A set of URLs associated with all of the applications in the tenant to log out the user.
A set of URLs associated with all of the applications the user is registered for to log out the user.
Unauthorized
URI
Variables
A string that defines why the user has been redirected to this page.
A string that defines the Id of each security incident generated by the Advanced Threat Detection suite.