# Custom module for two-factor authentication

> [HTML Version](two-factor-integration.html)

You can enable two‑step authentication when logging in to the system or the [external portal](service-portal.md), so that a user enters a verification code as the second factor. The user will receive this code through a third‑party service, for example a messenger.

To do this, create [a custom module](extentions.md) and then select it:

- In [the security settings](security_settings.md#two-factor-authentication) to enable two-factor authentication when logging in to the system.

- In [the settings of the external portal](portal-login-page.md#two-factor) on the **Authentication** tab to enable two-factor authentication for internal users when they log in to the portal.

````
начало внимание

````
Only users included in the [Administrators](360006871932.md#administrators) group can work with modules and configure them.

````
конец внимание

````
For example, let's configure receiving a verification code through a Telegram bot by following these steps:

1. Configure receiving a code from a third‑party service.

2. Create and configure a module.

3. Enable the module for the second authentication factor.

## Step 1: Configure receiving a code from a third-party service

1. Go to Telegram.

2. Create a bot. Read more in [the official Telegram documentation](https://core.telegram.org/bots/tutorial).

3. Copy the bot token.

4. Use the token to get a chat ID for the user. You can use the following method:

1. A user writes any message to the created bot.

2. After that the system administrator receives the user's chat ID with the bot.  
To do this:

- Enter the following request in the browser: \[OBJECT\], where \[OBJECT\] is the token received when creating the bot.

- In response to this request, you see a JSON text on the browser page, which contains the chat ID.

Example of JSON text

````
\{  
  "ok": true,  
  "result": \[  
    \{  
      "update\_id": 000000000,  
      "message": \{  
        "message\_id": 17,  
        "from": \{  
          "id": 0000000001,  
          "is\_bot": false,  
          "first\_name": "UserName",  
          "language\_code": "en"  
        \},  
        "chat": \{  
          "id": 0000000001,  
          "first\_name": "UserName",  
          "type": "private"  
        \},  
        "date": 1724073228,  
        "text": "Hi"  
      \}  
    \}  
  \]  
\}
````

5. ````
Specify the chat ID in the [Accounts](360004833572.md#accounts) field in the user profile. If the ID is not specified, the employee will only log in using the login and password.

## Step 2: Create and configure a module

Go to **Administration > Modules** and [create a module](create-extention.md). Then configure the settings on the **Settings** page that opens:

1. On the [Settings](extention-settings.md) tab, create [String](360009707032.md#string)-type properties that will be used in the script for receiving a verification code via a messenger bot:

- **Account Type** (\[OBJECT\]). The name of a third-party service through which two-factor authentication is configured.

- **Bot Token** (\[OBJECT\]). The bot ID on the external service side. Issued when creating a bot.

- **Message** (\[OBJECT\]). The message that a user will receive along with the verification code. For example, “To log in to BRIX, please enter this verification code: ”.

If all the properties are specified, go to the **Common** tab and click **Save**.

2. Go to the **API Methods** tab and click **Edit**. The method editor will open. Then, on the **Scripts** tab, write the code using the following template:

````
// This interface will allow you to set conditions in the function below that will prompt the user for the second factor authentication code  
interface SecondFactor\_sendError \{ error: string; skip2fa: boolean; \}  
  
// This function identifies a user login by the ID and receives a confirmation code  
async function secondFactor\_sendCode(userID: string, code: string): Promise<SecondFactor\_sendError> \{\}````
 

Example script for searching for a user login by the chat ID with a Telegram bot

````
interface SecondFactor\_sendError \{  
   error: string;  
   skip2fa: boolean;  
\}  
  
async function secondFactor\_sendCode(userID: string, code: string): Promise<SecondFactor\_sendError> \{  
   let params = await Namespace.getParams()  
   let accountType = params.data.accountType  
   const result: SecondFactor\_sendError = \{ error: "", skip2fa: false \};  
  
   const user = await System.users.search().where(f => f.\_\_id.eq(userID)).first();  
   if (\!user) \{  
       result.error = 'no user';  
       return result  
   \}  
   if (\!user.data.accounts) \{  
       result.error = 'user has no accounts';  
       result.skip2fa = true;  
       return result;  
   \}  
  
   for (var account of user.data.accounts) \{  
       if (account.type === accountType) \{  
           sendToTelegram(account.login, code);  
           return result;  
       \}  
   \}  
  
   result.error = 'user has no such account type';  
   result.skip2fa = true;  
  
   return result;  
\}  
async function sendToTelegram(chatId: string, code: string): Promise<void> \{  
   let params = await Namespace.getParams()  
   let botToken = params.data.botToken;  
   let message = params.data.message;  
   const method = 'sendMessage';  
  
   fetch("https://api.telegram.org/bot" + botToken + "/" + method, \{  
       method: "POST",  
       headers: \{  
           'Content-Type': 'application/json'  
       \},  
       body: JSON.stringify(\{ 'chat\_id': chatId, 'text': message + code \})  
   \});  
\}
````

## ````
Step 3: Enable the module for the second authentication factor

1. Go to **Administration > Modules**, open the module page and enable it.

2. In the window that opens, fill in the fields:

- **Bot token**. Add the value of the copied token.

- **Account type**. Add a name of a third-party service.

- **Message**. Add the text to be displayed before the verification code.

**(two-factor-integration-1.png)**

3. Save the settings. The module is ready for use.

4. Go to **Administration > Security Settings > Two-Factor Authentication** and select the configured [module for the second authentication factor](security_settings.md#two-factor-authentication).

Now, if the user has their Telegram bot chat ID specified in their profile, the employee will receive a confirmation code when logging in.

**(two-factor-integration-2.png)**