How-to: Keycloak - Customize the TOTP Text for Login page

Knowledge Base Community
, , ,
1

Description

By default, the Keycloak TOTP setup page displays instructions recommending authenticator applications. For example:

Install one of the following applications on your mobile:

  * Microsoft Authenticator
  * Google Authenticator
  * FreeOTP

Investigation:

In UCS, several texts on the Keycloak login page can be customized using UCR variables below the keycloak/login/messages/* namespace.

For general information, see the Keycloak app documentation:

https://docs.software-univention.de/keycloak-app/26.x/configuration.html#adjusting-texts-on-the-keycloak-login-page

The TOTP setup page uses additional Keycloak message keys. These keys are defined in the Keycloak login theme message files. The relevant upstream definitions can be found here:

https://github.com/keycloak/keycloak/blob/main/themes/src/main/resources/theme/base/login/messages/messages_en.properties#L132

Customizing the TOTP Setup Instructions

Step 1:

To replace the first TOTP setup instruction for the German (de) locale, set the loginTotpStep1 message using UCR:

ucr set keycloak/login/messages/de/loginTotpStep1="<YOUR TEXT>"

Replace <YOUR TEXT> with the text that should be displayed to users.

The general UCR variable format is:

keycloak/login/messages/<locale>/<message-key>

For example:

keycloak/login/messages/de/loginTotpStep1

Here, de specifies the German locale and loginTotpStep1 is the Keycloak message key used for the first step of the TOTP setup instructions.

Step 2:

After changing the UCR variable, reconfigure the Keycloak app to apply the customization:

univention-app configure keycloak

After the configuration has completed, Keycloak uses the customized text on the TOTP setup page for the configured locale.

1 Like