In this article, we will demo how to parameter Keycloak Multifactor authentication (MFA) using OTP


It is possible to configure Keycloak MFA almost out of the box.

In the following is demoed how to enable keycloak MFA using freeOTP.

Demo_otp realm

Let’s create a new realm demo_otp with 3 users.

(They can be created with user1/password user2/password and user3/password)

Keycloak Multifactor authentication

Modifying demo_otp Authentication Workflow

In demo_otp, the Authentication flow OTP form is updated from Optional to Required.

It means that any user authentication within the demo_otp realm will require a 2 factor authentication for authentication to succeed:

  • User/password (1st factor)
  • OTP challenge (2nd factor)

Keycloak Multifactor authentication

Mobile Authenticator

You need to download and install on your mobile FreeOTP or google Authenticator application.

Authentication of a user for the 1st time

It is assumed that the user has registered the mobile authenticator as mentioned previously.

Users have been created and provisioned with a default password.

A user will not be able to log directly, as he he will be asked to register a scan through his mobile authenticator.


  • The user click on http://localhost:8080/auth/realms/demo_otp/account
  • he/she logs as user3/password

Keycloak Multifactor authentication

  • The user is redirected to Mobile authenticator setup page
    • The user needs to scan the otp bar code
    • The user needs to register the challenge generated.




After having entered the Otp code, the user is successfully logged to keyclaok.

Keycloak Multifactor authentication

Authentication of a user (after 1st time)

The user will now always log using 2 steps.

The first consist of providing user credentials (username/password)

Keycloak Multifactor authentication

The second step consist of providing OTP challenge returned from the mobile authenticator device

Keycloak Multifactor authentication

Now the user is successfully logged to keycloak.

Keycloak Multifactor authentication

Keycloak OTP

Keycloak OTP solution can be deployed very easily out of the box.

Some points to have in mind when dealing with keycloak OTP

  • It is necessary to register a mobile authenticator such as FreeOTP/ Google Authenticator
  • For 1st time authentication user needs to register/scan a bar code
  • The bar code is on a per user-basis. It means that a new bar code is generated for each otp user
  • Keycloak OTP is using FreeOTP or google Authenticator as mobile authenticatior.
    • FreeOTP is based on TOTP (time OTP window ) or HMAC OTP.
    • Both of these technologies are very reliable and robust and cannot be forged unlike sms -OTP.

Olivier Rivat

Senior Software Engineer with over 25 years of experience doing Software Development, Support and Consulting in Identity and Access Management Solutions.
Specialised in IAM (security, access control, identity management) and Open Source integration, settled in 2004 by IAM industry veteran, JANUA offers high value-added products and services to businesses and governements with a concern for Identity Management and Open Source components.
JANUA provides better security, build relationships, and enable new cloud, mobile, and IoT offerings from any device or connected thing.
Olivier Rivat

Les derniers articles par Olivier Rivat (tout voir)