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

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

The headline change in V. 4.x is support for two-factor authentication (2FA) via OXAPI: accounts with 2FA enabled can now also authenticate headlessly. In V. 3.x, 2FA and OXAPI were mutually exclusive. In addition, the lifetimes of the OTP code and of the API challenge token are now configurable, and the 2FA OTP email can be customized as CMS content.

Prerequisites

  • You have OXID eShop version 7.5.

  • You are running PHP 8.3 or higher.

  • You have V. 3.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 ^4.0.0

  3. Run the database migrations.

    This creates the CMS content for the 2FA OTP email (table oxcontents, OXLOADID = oesm2faotpemail). No new tables or columns are created.

    ./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. 4.x and ready for use. Your existing 2FA settings are preserved.

Update notes

Default behavior after the update

The new OTP code lifetime (seconds) and API 2FA challenge lifetime (seconds) settings default to 300 seconds (5 minutes), matching the previously hardcoded value. The update does not change your customers’ login behavior; the 2FA activation state (shop-wide and per customer) is preserved.

2FA via OXAPI

2FA now also applies to logins via OXAPI. For details on connecting headless frontends, see Two-Factor Authentication via OXAPI.

Customizable OTP email

The 2FA OTP email is created as CMS content (oesm2faotpemail) during the update and can be customized. If no matching CMS content is present, the shop sends a built-in translated default email.

Minimum PHP requirement

  1. 4.x requires at least PHP 8.3 (tested up to PHP 8.5).

Known limitations in V. 4.x

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

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