Telegram bot for two-factor authentication

Free2FA is a free, Open Source two-factor authentication solution with push notifications based on FreeRADIUS, a Telegram bot and a web-based administrative control panel. Used with Cisco AnyConnect, suitable for any authorization systems with users from Active Directory.

The main components of the Free2FA system include:

Free2FA: This module is responsible for processing authentication requests through the Telegram bot, adding a second level of security after verifying the login and password.
FreeRADIUS: Used for initial verification of the user’s login and password. After successful verification, the request is forwarded to Free2FA for additional authentication using a second security factor.
SSSD: (System Security Services Daemon) For integration with the AD domain.

Free2FA microservices:

free2fa_setup: Dealt with initial system setup, including generating and managing required certificates.
free2fa_admin_html: Offers a web interface for system administration, allowing you to manage settings and users.
free2fa_admin_api: API service that provides communication between the administrative web interface and the server to perform administrative operations.
free2fa_api: The main API service that processes authentication requests and coordinates interaction with the Telegram bot to confirm user access.

Domain integration

To integrate a Linux machine into a domain and manage credentials, SSSD (System Security Services Daemon) is used, which meets modern security requirements. SSSD provides support for authentication through Kerberos, which is a standard for securely exchanging credentials in networked systems. Using Kerberos with SSSD ensures reliable and secure user accounts in a domain, providing centralized access control and authentication.

Installing Free2FA: Step by Step

Preparing the server

Creating a Telegram bot: The first step is to create a new bot via BotFather on Telegramto use it as a notification mechanism.
Server Tuning: Prepare a server based on Ubuntu Server 22.04 LTS. Make sure the server has at least 1 CPU core and 1024 MB of RAM. Depending on the expected load, resource requirements may be higher.
Creating a directory for settings: Open a terminal and run the commands to create a directory where the Free2FA settings will be stored:
```
mkdir -p /opt/2fa/ && cd /opt/2fa/
```
Running the installation script: Download and run the installation script using the following commands:
```
curl -o install.sh https://raw.githubusercontent.com/CLLlAgOB/free2fa/main/install.sh && bash install.sh
```
Follow the instructions that appear to complete the installation.
Setting up DNS for the admin panel: Create a DNS entry for the admin portal. Use the default address (https://free2fa_admin_html) or the one you specified in the parameters and set its value to ADDITIONAL_DNS_NAME_FOR_ADMIN_HTML. The default username and password for accessing the admin panel are set to admin/admin.

After completing these steps, the Free2FA system will be ready to use. You can set up two-factor authentication through the created Telegram bot to increase the security of access to your services.

Debugging and managing Free2FA

To manage and debug the Free2FA service, use the following commands:

For viewing Docker logsgo to the installation directory and run:

docker-compose logs -f

To access FreeRADIUS logsuse the command:

cat /var/log/freeradius/radius.log

For start FreeRADIUS in debug modefirst stop the service:

service freeradius stop

Then run FreeRADIUS with additional debugging options:

freeradius -Xx

Free2FA configuration

Configure Free2FA settings according to your requirements:

CA_EXPIRY_DAYS: Certificate authority validity period, in days.
FREE2FA_TELEGRAM_BOT_TOKEN: Telegram bot token.
FREE2FA_TELEGRAM_BOT_LANGUAGE: Bot language (ru or en).
FREE2FA_AUTO_REG_ENABLED: Automatic registration of new users without Telegram ID.
FREE2FA_BYPASS_ENABLED: Skip authentication for users without Telegram ID.
RADIUS_CLIENT_SECRET: Secret key for RADIUS.
FREE2FA_TIMEOUT: Maximum time to wait for login confirmation. (10-20 sec.)
RADIUS_START_SERVERS, RADIUS_MAX_SERVERS, RADIUS_MAX_SPARE_SERVERS, RADIUS_MIN_SPARE_SERVERS: Options for configuring RADIUS servers.
ADMIN_SECRET_KEY: Key to access the administration panel.
RESET_PASSWORD: Enable the password reset function.
ALLOW_API_FAILURE_PASS: Allow login without 2FA when Telegram API is unavailable.
ADDITIONAL_DNS_NAME_FOR_ADMIN_HTML: DNS name for the administrative panel.
RADIUS_CLIENT_IP: Expected RADIUS client IP address.

These parameters will help you customize the system to your specific requirements and ensure its efficient operation.

Setting up a RADIUS client

Time-out: Configure the timeout on the RADIUS client to be 3 seconds greater than the value FREE2FA_TIMEOUTinstalled for Free2FA.
Password management: Disable password management on the RADIUS client, if provided, as the current implementation does not support CHAPv2.

When you log in for the first time, you must change the administrator password to ensure security.

Note on working with user logins:

User logins in the database are saved in a unified format "domain\username", regardless of the input method. This ensures uniformity and consistency of data in the database, simplifying account management. Regardless of whether the user entered their login as:

In the database it will be written as "domain\username".

SSSD (System Security Services Daemon), used to integrate the system with the domain, is configured to operate in caching mode. This means that domain changes, such as credential updates or security policy changes, may take up to 20 minutes to appear on the client. Depending on security and performance requirements, caching can be configured for specific needs or disabled completely to ensure immediate response to changes in the domain.

For ease of managing settings on one server, it was added control.sh a script that allows you to configure several system configurations.

Repository link