Upgrading from V. 2.x to V. 3.x of the OXID Security Module

Upgrade the OXID Security Module from V. 2.x to V. 3.x if you are already running version 2.x.

The headline change in V. 3.x is two-factor authentication (2FA) via email OTP for storefront logins. After the update the feature is disabled by default — both shop-wide and per customer. It only takes effect once the shop admin enables it shop-wide and individual customers turn it on in their account.

Prerequisites

  • You have OXID eShop version 7.4.

  • You have V. 2.x of the OXID Security Module installed.

  • You deactivated the OXID Security Module before the update.

Procedure

  1. Open a shell and navigate to the root directory of your OXID eShop installation (the one containing composer.json).

    Example:

    cd /var/www/oxideshop/

  2. Update the module by running:

    composer require oxid-esales/security-module ^3.0.0

  3. Run the database migrations.

    This adds the new OE2FAENABLED column to the oxuser table and creates the new oesm_2fa_otp table.

    ./vendor/bin/oe-eshop-doctrine_migration migrations:migrate

  4. Activate the module in the admin panel under Extensions ‣ Modules or via the console:

    ./vendor/bin/oe-console oe:module:activate oe_security_module

    Alternatively, activate the module manually in the admin panel under Extensions ‣ Modules.

Result

The OXID Security Module is now at V. 3.x and ready for use. Two-factor authentication is disabled shop-wide by default. Once you enable 2FA shop-wide as the shop admin, your customers can switch on the feature themselves in their account under the security settings.

Update notes

Default behavior after the update

The update activates 2FA neither shop-wide nor for any individual customer. The feature only takes effect once you enable 2FA shop-wide as the shop admin AND individual customers enable 2FA in their account (the OE2FAENABLED column has a default value of 0). Existing customers face no extra login hurdles unless both steps are taken.

CAPTCHA validation moved

CAPTCHA validation has been moved from the User class to the UserComponent class. If you maintain a custom module that extends the User class, verify that it remains compatible.

Known limitations in V. 3.x

  • Logins in the admin backend are not protected by 2FA.

  • Accounts with 2FA enabled cannot authenticate via OXAPI. Such accounts must keep 2FA disabled to continue using OXAPI.

For more information, see the Release Notes for OXID Security Module V. 3.0.