Package org.opencms.security.twofactor

Class CmsTwoFactorAuthenticationHandler

  • public class CmsTwoFactorAuthenticationHandler
extends java.lang.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 Detail

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

      • 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:
        Constant Field Values

    • Method Detail

      • 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 java.lang.String getSetupMessage​(java.util.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