Package org.opencms.security.twofactor

Class CmsTwoFactorAuthenticationHandler

java.lang.Object
org.opencms.security.twofactor.CmsTwoFactorAuthenticationHandler
public class CmsTwoFactorAuthenticationHandler extends Object
Implements two-factor authentication for OpenCms users via TOTP.

This class can both set up a TOTP second factor for a user, as well as be used to authenticate a user using the verification code generated using their second factor.

  • Field Details

    • ALGORITHM

      public static final dev.samstevens.totp.code.HashingAlgorithm ALGORITHM
      The hashing algorithm to use.

      Other algorithms are technically possible, but potentially unsupported by some apps.

    • ATTR_TWOFACTOR_INFO

      public static final String ATTR_TWOFACTOR_INFO
      User info attribute for storing the second factor data.
      See Also:

    • DIGITS

      public static final int DIGITS
      The number of digits to use for verification codes.

      Other numbers are technically possible, but potentially unsupported by some apps.

      See Also:

    • KEY_SECRET

      public static final String KEY_SECRET
      JSON key for storing the shared secret.
      See Also:

    • KEY_USER

      public static final String KEY_USER
      JSON key for storing the user name.
      See Also:

  • Constructor Details

  • Method Details

    • generateSetupInfo

      public CmsSecondFactorSetupInfo generateSetupInfo(CmsUser user)
      Generates the information needed to share a secret with the user for the purpose of setting up 2FA.

      This contains both the data for a scannable QR code as well as the secret in textual form.

      Parameters:
      user - the user
      Returns:
      the second factor setup information

    • getSetupMessage

      public String getSetupMessage(Locale locale)
      Gets the message to display during two-factor authentication setup.
      Parameters:
      locale - the locale
      Returns:
      the message

    • hasSecondFactor

      public boolean hasSecondFactor(CmsUser user)
      Checks if there is already a second factor configured for the given user.

      For users excluded from two-factor authentication, this will usually return false, while for users who should use two-factor authentication, the result depends on whether the second factor has already been set up.

      Parameters:
      user - the user to check
      Returns:
      true if there is a second factor set up for the given user

    • isEnabled

      public boolean isEnabled()
      Checks if two-factor authentication is enabled.
      Returns:
      true if two-factor auth is enabled

    • needsTwoFactorAuthentication

      public boolean needsTwoFactorAuthentication(CmsUser user)
      Checks if two-factor authentication should be used for the given user.
      Parameters:
      user - the user to check
      Returns:
      true if two-factor authentication should be used

    • resetTwoFactorAuthentication

      public void resetTwoFactorAuthentication(CmsUser user)
      Deletes the two-factor authentication in the user object, but does not write the user to the database.
      Parameters:
      user - the user for whom 2FA should be reset

    • setUpAndVerifySecondFactor

      public boolean setUpAndVerifySecondFactor(CmsUser newUser, CmsSecondFactorInfo code) throws CmsSecondFactorSetupException
      Sets up the second factor for the given user, and immediately verifies it with the authentication code given.
      Parameters:
      newUser - the user for whom to set up the second factor
      code - contains both the shared secret and the authentication code generated by the user
      Returns:
      true if the second factor could be set up, false if the verification failed
      Throws:
      CmsSecondFactorSetupException - in unexpected circumstances, e.g. if the user already has a second factor set up or there is no authentication code

    • trackUserChange

      public void trackUserChange(CmsRequestContext requestContext, CmsUser oldUser, CmsUser newUser)
      Gets called when a user is changed so we can check if the second factor information was changed and generate appropriate log messages.
      Parameters:
      requestContext - the current request context
      oldUser - the user before modification
      newUser - the user after modification

    • verifySecondFactor

      public boolean verifySecondFactor(CmsUser user, CmsSecondFactorInfo secondFactorInfo)
      Verifies the second factor information for a user.

      Note that this method assumes that two-factor authentication should be applied to the given user, and always checks the second factor.

      Parameters:
      user - the user
      secondFactorInfo - the second factor information
      Returns:
      true if the verification was successful

    • verifySecondFactorSetup

      public boolean verifySecondFactorSetup(CmsSecondFactorInfo secondFactorInfo)
      Verifies that the verification code is correct for a secret.
      Parameters:
      secondFactorInfo - object containing the secret and verification code
      Returns:
      true if the verification is successful