search string side menu

Modules > Examples of BRIX integration modules / Custom module for two-factor authentication

Custom module for two-factor authentication

You can enable two‑step authentication when logging in, 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 and then select it in the security settings.

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

Only users included in the 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.
  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: https://api.telegram.org/bottoken/getUpdates, where token 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"
     }
   }
 ]
}
  1. Then specify the chat ID in the 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. Then configure the settings on the Settings page that opens:

  1. On the Settings tab, create String-type properties that will be used in the script for receiving a verification code via a messenger bot:
  • Account Type (accountType). The name of a third-party service through which two-factor authentication is configured.
  • Bot Token (botToken). The bot ID on the external service side. Issued when creating a bot.
  • Message (message). 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.

  1. 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 accountType = Namespace.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;
}
 
function sendToTelegram(chatId: string, code: string):void {
 
 
   let botToken = Namespace.params.data.botToken;
   let message = Namespace.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

  1. Save the settings. The module is ready for use.
  2. Go to Administration > Security Settings > Two-Factor Authentication and select the configured module for the second authentication factor.

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

external-oauth2-integration.html sms-integration.html