Skip to content

Enable Two-Factor Authentication (2FA)

To enhance the security of your Ozone distribution, you can enable Two-Factor Authentication (2FA) for user accounts. This adds a layer of protection by requiring users to provide a second form of verification during the login process. Ozone comes with Keycloak as the default Identity provider (IdP) solution, which supports 2FA.

In this section, we will cover the steps to enable 2FA in your Ozone distribution by modifying the Keycloak realm configuration.

Overriding Ozone Realm Configuration

By default, 2FA is disabled in Keycloak. To enable it, you need to modify the realm configuration file used by Keycloak in your Ozone distribution package. This file is located in the distro/configs/keycloak/realms/ozone-realm.json directory of your Ozone distribution. To override the default realm configuration, create a copy of the ozone-realm.json file from the distro/configs/keycloak/realms/ directory and place it in the configs/keycloak/realms/ directory of your Ozone distribution.

The default Ozone realm configuration file will be overridden by the one in the configs/keycloak/realms/ directory during the build process. Now, you can proceed to enable 2FA by modifying the copied ozone-realm.json file. In the next sections, we will guide you through the necessary changes to enable 2FA.

Enabling 2FA in Keycloak

There are two main steps to enable 2FA in Keycloak:

  1. Enable the Authenticator Flow: You need to enable the "Browser - Conditional OTP" flow in Keycloak. This flow requires users to provide a one-time password (OTP) generated by an authenticator app during login.
  2. Configure the Required Actions: You need to configure the required actions for users to set up their authenticator app when they log in for the first time.

Step 1: Enable the Authenticator Flow

  1. Open the copied ozone-realm.json file in a text editor.
  2. Locate the authenticationFlows section in the JSON file.
  3. Find the flow named "Browser - Conditional OTP" and set its enabled property to true. If the flow does not exist, you can add it. Below is an example of how to define the "Browser - Conditional OTP" flow: 
    {
    "alias": "Browser - Conditional OTP",
    "description": "Browser authentication with conditional OTP",
    "providerId": "basic-flow",
    "topLevel": true,
    "builtIn": true,
    "enabled": true,
    "authenticationExecutions": [
     {
       "authenticator": "conditional-user-configured",
       "authenticatorFlow": false,
       "requirement": "REQUIRED",
       "priority": 10,
       "userSetupAllowed": false,
       "autheticatorFlow": false
     },
     {
       "authenticator": "auth-otp-form",
       "authenticatorFlow": false,
       "requirement": "REQUIRED",
       "priority": 20,
       "userSetupAllowed": false,
       "autheticatorFlow": false
     }
   ]
}
    The authentication executions define the steps in the flow, where the first step checks if the user has configured OTP, and the second step prompts for the OTP during login. Based on the priority, you can adjust the order of execution if needed. By setting the enabled property to true, you activate this flow in Keycloak.

Now, save the changes to the ozone-realm.json file before proceeding to the next step. At this point, you have enabled the authenticator flow for 2FA in Keycloak.

Step 2: Configure the Required Actions

  1. In the same ozone-realm.json file, locate the requiredActions section.
  2. Add a new required action for the "Configure OTP" action. This action will prompt users to set up their authenticator app during their first login. Add the following JSON object to the requiredActions array: 
    {
    "alias": "CONFIGURE_TOTP",
    "name": "Configure OTP",
    "providerId": "configure-totp",
    "enabled": true,
    "defaultAction": false,
    "priority": 0
}
  3. Save the changes to the ozone-realm.json file. if you have not done so already, ensure that the modified ozone-realm.json file is placed in the configs/keycloak/realms/ directory of your Ozone distribution.

By following these steps, you will have successfully enabled Two-Factor Authentication (2FA) in your Ozone distribution, enhancing the security of user accounts.

User Experience with 2FA Enabled

Once 2FA is enabled, users will experience the following during the login process:

  1. Initial Login: When a user logs in for the first time after 2FA has been enabled, they will be prompted to set up their authenticator app. This involves scanning a QR code or entering a setup key manually.
  2. Subsequent Logins: For all subsequent logins, users will be required to enter a one-time code generated by their authenticator app in addition to their username and password.
  3. Account Management: Users can manage their 2FA settings, including reconfiguring their authenticator app or viewing recovery codes, through the account management console.