Setting up authorization via Telegram 1C-Bitrix

Telegram Authorization Configuration in 1C-Bitrix

Telegram Login Widget is Telegram's official mechanism for authorization on third-party sites. Unlike OAuth providers (VKontakte, Google), it works with its own protocol: user data is transmitted via HMAC-SHA256 hash with a key from the bot token. 1C-Bitrix has no standard module for Telegram authorization, so integration is done manually or via a third-party module.

Telegram Login Widget Workflow

1. Authorization page displays a Telegram widget (script telegram.org/js/telegram-widget.js).
2. User clicks the button, confirms in Telegram app that they trust the site.
3. Telegram sends to callback URL (or JS callback) an object with fields: id, first_name, last_name, username, photo_url, auth_date, hash.
4. Server verifies signature: builds data-check-string from all fields (except hash), calculates HMAC-SHA256 with key SHA256(bot_token), and compares with hash.
5. Checks auth_date — not older than 86400 seconds (replay-attack protection).
6. After verification — authorizes or registers the user.

Creating a Bot

The authorization widget is tied to a Telegram bot. Create a bot: @BotFather → /newbot. Then set domain: /setdomain → @your_bot → your-site.com. Without this the widget won't work — Telegram validates the request origin.

Bot token is used only on the server for signature verification. Never expose the token to the frontend.

Implementation in Bitrix

Create component /local/components/custom/telegram.auth/. In component template place the widget:

<script async src="https://telegram.org/js/telegram-widget.js?22"
    data-telegram-login="your_bot_name"
    data-size="large"
    data-auth-url="https://your-site.com/auth/telegram/callback/"
    data-request-access="write">
</script>

Callback handler (/local/php_interface/include/auth/telegram_callback.php or via Bitrix router):

\Bitrix\Main\Loader::includeModule('main');

$data = $_GET;
$hash = $data['hash'];
unset($data['hash']);

ksort($data);
$checkString = implode("\n", array_map(fn($k, $v) => "$k=$v", array_keys($data), $data));

$secretKey = hash('sha256', $botToken, true);
$computedHash = hash_hmac('sha256', $checkString, $secretKey);

if (!hash_equals($computedHash, $hash)) {
    // Invalid signature
    LocalRedirect('/auth/?error=invalid_signature');
}

if ((time() - (int)$data['auth_date']) > 86400) {
    LocalRedirect('/auth/?error=expired');
}

// Find user by Telegram ID in custom field or table
$telegramId = (int)$data['id'];
$user = \Bitrix\Main\UserTable::getList([
    'filter' => ['UF_TELEGRAM_ID' => $telegramId],
    'select' => ['ID'],
    'limit'  => 1,
])->fetch();

if ($user) {
    // Authorize
    $GLOBALS['USER']->Authorize($user['ID']);
} else {
    // Register new user
    $newUser = new CUser();
    $userId = $newUser->Add([
        'LOGIN'      => 'tg_' . $telegramId,
        'NAME'       => $data['first_name'] ?? '',
        'LAST_NAME'  => $data['last_name'] ?? '',
        'ACTIVE'     => 'Y',
        'PASSWORD'   => randString(20),
        'UF_TELEGRAM_ID' => $telegramId,
    ]);
    $GLOBALS['USER']->Authorize($userId);
}

LocalRedirect('/personal/');

Field UF_TELEGRAM_ID is created via Settings → Users → Custom Fields with type "Integer".

Common Issues

• "Bot domain invalid" — domain not configured in @BotFather. Domain is specified without protocol and slash.
• "Hash invalid" — server uses $_GET instead of verified data, or extra fields are added to data.
• Works only over HTTPS — Telegram Widget requires SSL on target domain.

Timeframe

Implementing Telegram authorization from scratch: 4–6 hours (bot, component, handler, custom field, button template).