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.

    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

    application [Application]

    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.

    client_id [String]

    The OAuth v2.0 client_id parameter. This is synonymous with FusionAuth’s Application Id.

    currentUser [User] Available since 1.30.0

    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 undefined.

    errorMessages [Array<String>]

    A list of error messages that were generated during the processing of the request.

    fieldMessages [Map<String, List<String>>]

    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.

    locale [Locale]

    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

    request [HttpServletRequest]

    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

    tenant [Tenant]

    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 maintainance, 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.

    tenantId [UUID]

    The unique Tenant identifier, this is equivalent to tenant.id.

    theme [Theme]

    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.

    themeId [UUID]

    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

    Available Since Version 1.26.0.

    /account/edit

    Variables

    fields [Map<Integer, List<FormField>>]

    The User fields to display in the form. Each key maps to form fields by section within a Self-Service User form.

    user [User]

    The User object corresponding to the authenticated user.

    Account index

    Available Since Version 1.26.0.

    /account

    Variables

    formConfigured [Boolean]

    A boolean that indicates if a Self-Service User form has been configured for this application.

    multiFactorAvailable [Boolean]

    A boolean that indicates if any multi-factor authentication methods have been enabled on the tenant.

    user [User]

    The User object corresponding to the authenticated user.

    Account two-factor disable

    Available Since Version 1.26.0.

    /account/two-factor/disable

    Variables

    email [String]

    The email address you are attempting to disable, this will be available when the method is email.

    method [String]

    The two-factor method you are disabling. The possible values are:

    • authenticator

    • email

    • sms

    methodId [String]

    The actual Id of the two-factor method you are disabling.

    mobilePhone [String]

    The mobile phone you are attempting to disable, this will be available when the method is sms.

    user [User]

    The User object corresponding to the authenticated user.

    Account two-factor enable

    Available Since Version 1.26.0.

    /account/two-factor/enable

    Variables

    availableMethods [List<String>]

    The two-factor methods that are available to be configured.

    email [String]

    The email address if the method value is email.

    method [String]

    The two-factor method. The possible values are:

    • authenticator

    • email

    • sms

    mobilePhone [String]

    The mobile phone if the method is sms.

    recoveryCodes [List<String>]

    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.

    secret [String]

    A Base64 encoded secret for the authenticator method.

    secretBase32Encoded [String]

    A Base32 encoded form of the provided secret for the authenticator method.

    user [User]

    The User object corresponding to the authenticated user.

    Account two-factor index

    Available Since Version 1.26.0.

    /account/two-factor

    Variables

    user [User]

    The User object corresponding to the authenticated user.

    Email verification complete

    /email/complete

    No page specific variables.

     

    Email verification re-sent

    /email/sent

    Variables

    email [String]

    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.

    emailSent [Boolean]

    A boolean that indicates if the verification email was re-sent or not.

    Email verification required

    Available Since Version 1.27.0.

    /email/verification-required

    Variables

    allowEmailChange [Boolean]

    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.

    collectVerificationCode [Boolean]

    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.

    email [String]

    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.

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    verificationId [String]

    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

    /email/verify

    Variables

    postMethod [Boolean]

    Defaults to true on this page.

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    verificationId [String]

    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

    Available Since Version 1.27.0.

    /

    No page specific variables.

     

    OAuth authorize

    /oauth2/authorize

    Variables

    code_challenge [String]

    The OAuth v2.0 code_challenge parameter.

    code_challenge_method [String]

    The OAuth v2.0 code_challenge_method parameter used in conjunction with PKCE. Can be either plain or S256.

    devicePendingIdPLink [Object]

    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).

    devicePendingIdPLink.displayName [String]

    A human readable name for this link to help you identify this link. This value will generally be an email address, or username.

    devicePendingIdPLink.email [String]

    The email address of the FusionAuth user being linked to the identity provider.

    devicePendingIdPLink.identityProviderLinks [List<Object>]

    See full documentation for this object here

    devicePendingIdPLink.identityProviderName [String]

    The name of the identity provider that is being linked to.

    devicePendingIdPLink.identityProviderType [String]

    The type of identity provider that is being linked to.

    devicePendingIdPLink.identityProviderUserId [String]

    The Id for the User that is provided by the identity provider.

    devicePendingIdPLink.linkLimitExceeded [Boolean]

    A boolean that indicates if a user has exceeded the maximum number of links allowed.

    devicePendingIdPLink.user [User]

    The FusionAuth user that is linked to the identity provider.

    devicePendingIdPLink.username [String]

    The username of the FusionAuth user being linked to the identity provider.

    hasDomainBasedIdentityProviders [Boolean]

    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.

    identityProviders [Map<String, List<Object>>]

    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.

    loginId [String]

    The value from the loginId form field. This is either the username or the email of the user attempting to log into FusionAuth.

    metaData [MetaData]

    Metadata on when the JWT Refresh Token was created

    nonce [String]

    The OpenID Connect nonce request parameter.

    passwordlessEnabled [Boolean]

    A boolean that controls whether or not to to utilize a passwordless flow.

    pendingIdpLink [Object]

    This is the unique value when creating a link between a unique UUID returned by the IdP and a new or existing FusionAuth user.

    pendingIdpLink.displayName [String]

    A human readable name for this link to help you identify this link. This value will generally be an email address, or username.

    pendingIdpLink.email [String]

    The email address of the FusionAuth user being linked to the identity provider.

    pendingIdpLink.identityProviderLinks [List<Object>]

    See full documentation for this object here

    pendingIdpLink.identityProviderName [String]

    The name of the identity provider that is being linked to.

    pendingIdpLink.identityProviderType [String]

    The type of identity provider that is being linked to.

    pendingIdpLink.identityProviderUserId [String]

    The Id for the User that is provided by the identity provider.

    pendingIdpLink.linkLimitExceeded [Boolean]

    A boolean that indicates if a user has exceeded the maximum number of links allowed.

    pendingIdpLink.user [User]

    The FusionAuth user that is linked to the identity provider.

    pendingIdpLink.username [String]

    The username of the FusionAuth user being linked to the identity provider.

    redirect_uri [String]

    The OAuth v2.0 redirect_uri parameter. This is the URI that FusionAuth will redirect the user to once they have successfully logged in.

    rememberDevice [String]

    This value is used to record if ths user would like to have their device remembered on the next login.

    response_type [String]

    The OAuth v2.0 response_type parameter.

    scope [String]

    The OAuth v2.0 scope parameter.

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    showPasswordField [Boolean]

    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.

    state [String]

    The OAuth v2.0 state parameter.

    timezone [String]

    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.

    user_code [String]

    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.

    version [String]

    The version.

    OAuth authorized not registered

    Available Since Version 1.28.0.

    /oauth2/authorized-not-registered

    No page specific variables.

     

    OAuth child registration not allowed

    /oauth2/child-registration-not-allowed

    Variables

    parentEmail [String]

    The parent’s email address provided in the input field of the form.

    OAuth child registration not allowed complete

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

    No page specific variables.

     

    OAuth complete registration

    /oauth2/complete-registration

    No page specific variables.

     

    OAuth device

    Available Since Version 1.11.0.

    /oauth2/device

    Variables

    devicePendingIdPLink [Object]

    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).

    devicePendingIdPLink.displayName [String]

    A human readable name for this link to help you identify this link. This value will generally be an email address, or username.

    devicePendingIdPLink.email [String]

    The email address of the FusionAuth user being linked to the identity provider.

    devicePendingIdPLink.identityProviderLinks [List<Object>]

    See full documentation for this object here

    devicePendingIdPLink.identityProviderName [String]

    The name of the identity provider that is being linked to.

    devicePendingIdPLink.identityProviderType [String]

    The type of identity provider that is being linked to.

    devicePendingIdPLink.identityProviderUserId [String]

    The Id for the User that is provided by the identity provider.

    devicePendingIdPLink.linkLimitExceeded [Boolean]

    A boolean that indicates if a user has exceeded the maximum number of links allowed.

    devicePendingIdPLink.user [User]

    The FusionAuth user that is linked to the identity provider.

    devicePendingIdPLink.username [String]

    The username of the FusionAuth user being linked to the identity provider.

    interactive_user_code [String]

    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.

    userCodeLength [Integer]

    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

    Available Since Version 1.12.0.

    /oauth2/device-complete

    Variables

    completedLinks [List<PendingIdPLink>] Available since 1.30.0

    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

    /oauth2/error

    Variables

    oauthJSONError [String]

    The OAuth error JSON that could be helpful for developers while debugging.

    OAuth logout

    /oauth2/logout

    Variables

    allLogoutURLs [Set<String>]

    A set of URLs associated with all of the applications in the tenant to log out the user.

    redirectURL [String]

    The URL to be redirected to after the front-channel logout occur.

    registeredLogoutURLs [Set<String>]

    A set of URLs associated with all of the applications the user is registered for to log out the user.

    OAuth passwordless

    /oauth2/passwordless

    Variables

    redirect_uri [String]

    The OAuth v2.0 redirect_uri parameter. This is the URI that FusionAuth will redirect the user to once they have successfully logged in.

    response_type [String]

    The OAuth v2.0 response_type parameter.

    scope [String]

    The OAuth v2.0 scope parameter.

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    state [String]

    The OAuth v2.0 state parameter.

    timezone [String]

    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

    /oauth2/register

    Variables

    collectBirthDate [Boolean]

    Whether or not to collect a birth date for a Consent workflow.

    hideBirthDate [Boolean]

    Whether or not to render a hidden field for passing along the birthdate in the form.

    parentEmailRequired [Boolean]

    Whether or not a parent’s email address is required for a Consent Workflow.

    passwordValidationRules [Object]

    An object that contains the password validation rules. The object fields are defined in keys to this object, as defined below.

    passwordValidationRules.maxLength [Integer]

    The maximum length of a password.

    passwordValidationRules.minLength [Integer]

    The minimum length of a password.

    passwordValidationRules.rememberPreviousPasswords.count [Integer]

    The number of previous passwords the user is not allowed to re-use.

    passwordValidationRules.requireMixedCase [Boolean]

    Whether or not the user must use upper and lower-cased letter.

    passwordValidationRules.requireNonAlpha [Boolean]

    Whether or not the user must use at least one non-alphabetic character in their password.

    passwordValidationRules.requireNumber [Boolean]

    Whether or not the user must use at least one numeric character in their password.

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    Available Since Version 1.28.0.

    /oauth2/start-idp-link

    Variables

    devicePendingIdPLink [Object]

    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).

    devicePendingIdPLink.displayName [String]

    A human readable name for this link to help you identify this link. This value will generally be an email address, or username.

    devicePendingIdPLink.email [String]

    The email address of the FusionAuth user being linked to the identity provider.

    devicePendingIdPLink.identityProviderLinks [List<Object>]

    See full documentation for this object here

    devicePendingIdPLink.identityProviderName [String]

    The name of the identity provider that is being linked to.

    devicePendingIdPLink.identityProviderType [String]

    The type of identity provider that is being linked to.

    devicePendingIdPLink.identityProviderUserId [String]

    The Id for the User that is provided by the identity provider.

    devicePendingIdPLink.linkLimitExceeded [Boolean]

    A boolean that indicates if a user has exceeded the maximum number of links allowed.

    devicePendingIdPLink.user [User]

    The FusionAuth user that is linked to the identity provider.

    devicePendingIdPLink.username [String]

    The username of the FusionAuth user being linked to the identity provider.

    pendingIdpLink [Object]

    This is the unique value when creating a link between a unique UUID returned by the IdP and a new or existing FusionAuth user.

    pendingIdpLink.displayName [String]

    A human readable name for this link to help you identify this link. This value will generally be an email address, or username.

    pendingIdpLink.email [String]

    The email address of the FusionAuth user being linked to the identity provider.

    pendingIdpLink.identityProviderLinks [List<Object>]

    See full documentation for this object here

    pendingIdpLink.identityProviderName [String]

    The name of the identity provider that is being linked to.

    pendingIdpLink.identityProviderType [String]

    The type of identity provider that is being linked to.

    pendingIdpLink.identityProviderUserId [String]

    The Id for the User that is provided by the identity provider.

    pendingIdpLink.linkLimitExceeded [Boolean]

    A boolean that indicates if a user has exceeded the maximum number of links allowed.

    pendingIdpLink.user [User]

    The FusionAuth user that is linked to the identity provider.

    pendingIdpLink.username [String]

    The username of the FusionAuth user being linked to the identity provider.

    registrationEnabled [Boolean]

    A boolean that indicates if the application is configured for self registration.

    OAuth two-factor

    /oauth2/two-factor

    Variables

    code [String]

    The value of the code form field on the page. This will be available only after the user has submitted the form.

    method [TwoFactorMethod] Available since 1.26.0

    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.

    methodId [String] Available since 1.26.0

    The method Id. This Id, if defined, will represent the currently selected method, or last used method.

    pushEnabled [Boolean] Deprecated

    Whether or not FusionAuth has pushed (SMS) enabled for two-factor. Removed in version 1.26.0

    pushPreferred [Boolean] Deprecated

    Whether or not the user prefers push (SMS) for two-factor. Removed in version 1.26.0

    redirect_uri [String]

    The OAuth v2.0 redirect_uri parameter. This is the URI that FusionAuth will redirect the user to once they have successfully logged in.

    resendCode [Boolean] Deprecated

    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

    response_type [String]

    The OAuth v2.0 response_type parameter.

    scope [String]

    The OAuth v2.0 scope parameter.

    showResendOrSelectMethod [Boolean]

    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.

    state [String]

    The OAuth v2.0 state parameter.

    timezone [String]

    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.

    trustComputer [Boolean]

    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.

    twoFactorId [String]

    The unique Id of the current multi-factor authentication attempt.

    userCanReceivePush [Boolean] Deprecated

    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 methods

    Available Since Version 1.26.0.

    /oauth2/two-factor-methods

    Variables

    availableMethodsMap [Map<String, TwoFactorMethod>]

    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.

    methodId [String]

    The method Id. This Id, if defined, will represent the currently selected method, or last used method.

    recoverCodesAvailable [Integer]

    The total number of recovery codes that the user has available to use.

    timezone [String]

    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.

    twoFactorId [String]

    The unique Id of the current multi-factor authentication attempt.

    OAuth wait

    Available Since Version 1.12.0.

    /oauth2/wait

    Variables

    code [String]

    The FusionAuth temporary code used to complete this external authentication request.

    OAuth Change password form

    /password/change

    Variables

    changePasswordId [String]

    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.

    passwordValidationRules [Object]

    An object that contains the password validation rules. The object fields are defined in keys to this object, as defined below.

    passwordValidationRules.maxLength [Integer]

    The maximum length of a password.

    passwordValidationRules.minLength [Integer]

    The minimum length of a password.

    passwordValidationRules.rememberPreviousPasswords.count [Integer]

    The number of previous passwords the user is not allowed to re-use.

    passwordValidationRules.requireMixedCase [Boolean]

    Whether or not the user must use upper and lower-cased letter.

    passwordValidationRules.requireNonAlpha [Boolean]

    Whether or not the user must use at least one non-alphabetic character in their password.

    passwordValidationRules.requireNumber [Boolean]

    Whether or not the user must use at least one numeric character in their password.

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    OAuth password complete

    /password/complete

    No page specific variables.

     

    Forgot password

    /password/forgot

    Variables

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    Forgot password sent

    /password/sent

    No page specific variables.

     

    Verify registration complete

    /registration/complete

    No page specific variables.

     

    Verify registration re-sent

    /registration/sent

    Variables

    applicationId [UUID]

    The Id of the application that the user is verifying their email for and needs the email to be resent.

    email [String]

    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.

    emailSent [Boolean]

    A boolean that indicates if the verification email was re-sent or not.

    Verify registration required

    Available Since Version 1.27.0.

    /registration/verification-required

    Variables

    collectVerificationCode [Boolean]

    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.

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    verificationId [String]

    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

    /registration/verify

    Variables

    showCaptcha [Boolean] Available since 1.30.0

    A boolean that controls whether or not to include captcha scripts and show the captcha challenge (or message for invisible captcha).

    verificationId [String]

    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

    Available Since Version 1.25.0.

    /samlv2/logout

    Variables

    allLogoutURLs [Set<String>]

    A set of URLs associated with all of the applications in the tenant to log out the user.

    registeredLogoutURLs [Set<String>]

    A set of URLs associated with all of the applications the user is registered for to log out the user.

    Unauthorized

    Available Since Version 1.30.0.

    /unauthorized

    Variables

    cause [String]

    A string that defines why the user has been redirected to this page.

    incidentId [String]

    A string that defines the Id of each security incident generated by the Advanced Threat Detection suite.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo