Two-factor authentication (Google / Yandex.Key) (EcomLabs)

What this solution does

Two-factor authentication module based on the TOTP standard (RFC 6238). Supports Yandex Key, Google Authenticator, Microsoft Authenticator, and compatible applications. Features include multi-device support, backup code generation, and the ability to enforce authentication for specific user groups. The component operates in the administrative panel and on the public storefront without requiring the Proactive Protection module.

Login with active 2FA: after entering the username and password, the system requests confirmation. The user enters a six-digit code from the authenticator app or a backup code. Upon successful verification, the session is marked as confirmed, and the user is redirected to the original URL (admin panel or website).

Mandatory authentication without devices: if a user logs in as part of a group defined in the mandatory groups setting but has not yet set up 2FA, they are redirected to the setup page after entering their password. This page generates a QR code and requires two consecutive code entries for confirmation.

Voluntary setup: performed via the ecl:yandex2fa.setup component in the personal account or through a URL with the setup parameter. The process involves generating a secret key, displaying a QR code using the otpauth://totp/ protocol, confirming with two codes, and issuing a one-time list of backup codes.

Multiple devices: several authenticators can be added to a single account, with a configurable limit. Device removal or disabling respects the group policy requiring two-factor authentication.

Trust session: after successful 2FA, a trust session is active for a configurable duration in minutes, preventing code requests on every hit within the TTL.

Security: device secrets are stored securely on the server; backup codes are stored only as hashes, with the plaintext displayed once upon issuance.

TOTP validation: uses a validation window of ±N periods of 30 seconds and includes protection against replay attacks.

Access limits: configurable attempt limits and temporary blocking are enforced.

Protocol: optional enforcement of HTTPS-only code submission.

Data storage: 2FA trust status is stored in a dedicated module table, not in b_option.

Logging: critical actions are recorded in the module log.

Service URLs

Code entry (challenge): /bitrix/tools/ecl_yandex2fa_auth.php

2FA setup: /bitrix/tools/ecl_yandex2fa_setup.php

AJAX setup: /bitrix/tools/ecl_yandex2fa_setup_ajax.php

The challenge and setup paths can be overridden in module settings. Components are recommended for embedding in site templates.

2. Settings and pages in the admin panel

2.1. Module settings

The configuration for the Two-Factor Authentication module (Google / Yandex.Key) by EcomLabs is located in the Product Settings menu under Module Settings, or directly within the module's Settings menu item.

Module Enabled: Global switch for 2FA functionality without removing the module. Default is Off (N); activation is required after installation.

HTTPS Only: Rejects code verification requests sent over the HTTP protocol. Default is Off (N).

Groups Requiring 2FA: Multi-select list of user groups. Users in these groups cannot complete login without an active device and will be redirected to the setup process. Default is the Administrators group (ID 1).

Verification Window, Periods ±: Time tolerance for TOTP (base period 30 seconds). Standard value is 1.

HMAC Algorithm: Hashing method for new connections (SHA-1, SHA-256, or SHA-512). Google Authenticator supports only SHA-1. Default is sha1.

Backup Codes Count: Number of one-time recovery codes generated during enrollment or reissue. Range is 8 to 20, default is 10.

Max Devices Per User: Limit on active devices allowed per account. Range is 1 to 20, default is 5.

Session Trust Duration After 2FA, Minutes: TTL trust period after a successful code verification. Default is 720 minutes (12 hours).

Attempts Before Lockout: Number of consecutive failed verification attempts before locking. Default is 5.

Lockout Duration, Seconds: Pause time after exhausting the attempt limit. Default is 900 seconds.

Issuer: Label displayed in the authenticator application. If left empty, the site name from main settings is used.

The module provides two-factor authentication with support for Google Authenticator and Yandex Key. To ensure compatibility with applications that have UTF-8 encoding issues (such as Drop Authenticator), ASCII labels and Cyrillic transliteration are used in the label and issuer fields of the QR codes. Standard Google and Yandex applications correctly handle UTF-8.

By default, the code entry page and the 2FA setup page are located at /bitrix/tools/ecl_yandex2fa_auth.php and /bitrix/tools/ecl_yandex2fa_setup.php respectively. User hints are configured via a text field; if left empty, the built-in instructions for Google Authenticator and Yandex Key are displayed.

In the Bitrix admin menu section Users with 2FA, a list of users is shown with columns for ID, login, name, 2FA activity status, number of linked devices, registration date, usage of backup codes, and other data. A function to reset 2FA for a specific user is available (requires confirmation), which clears device data and backup codes and resets trusted sessions.

The Log section records events: enrollment, verification, recovery code usage, errors, and resets. The log displays the date, user, action type, IP address, and event description.

The component ecl:yandex2fa.auth is designed to display the login confirmation or 2FA status block. It can be placed on any page of the site, including replacing standard tool URLs. For guests, the system prompts to log in with a username and password first. If a code is required, a form for entering a TOTP or backup code is displayed.

Two-factor authentication (2FA) module for Google and Yandex.Key systems by eCom Labs. If the login is already verified and the corresponding parameter is active, the system displays a message indicating that re-entry is not required. When 2FA is not required or the module is disabled, the corresponding status is shown.

Key configuration parameters include AJAX_MODE (AJAX mode, default value Y), SHOW_VERIFIED (display block if login is already confirmed), and standard caching settings CACHE_TYPE and CACHE_TIME.

The ecl:yandex2fa.setup component handles device connection and management. Features include viewing the device list, adding a new device, generating a QR code, entering two codes, issuing one-time recovery codes, removing a device, reissuing recovery codes, and disabling 2FA (if permitted by group policy). The module operates independently on the profile page at the /tools/setup path.

With AJAX_MODE enabled (default value Y), actions are processed via the ecl_yandex2fa_setup_ajax.php file. The tools page displays a centered card with a button to return to the site. Composite support is available.

It is recommended to place the ecl:yandex2fa.setup component within the personal cabinet. The login challenge can remain on the tools page or the ecl:yandex2fa.auth component can be displayed on a custom login page.

When implementing “Two-factor authentication (Google / Yandex.Key) (EcomLabs)”, General iT can help with installation, adaptation and launch preparation.