Chi tiết luồng xác thực Telegram

Plugin Telegram hỗ trợ hai luồng xác thực: Login Widget (web browser) và Web App (Telegram Mini App). Cả hai đều dùng HMAC-SHA256 nhưng với key khác nhau.

Luồng A: Login Widget

Dùng cho đăng nhập trên web browser thông qua Telegram Login Widget.

Sequence diagram

Chi tiết HMAC verification

Telegram Login Widget gửi auth data cùng hash để chứng minh dữ liệu từ Telegram. Cách verify:

1. Lấy tất cả params trừ hash
2. Sắp xếp theo tên alphabetically
3. Nối thành string: key=value, mỗi cặp cách nhau bởi \n
4. Tính secret = SHA256(bot_token)
5. Tính expected = HMAC_SHA256(secret, data_check_string)
6. So sánh expected với hash (cả hai dạng hex)

Ví dụ:

data_check_string:
auth_date=1234567890
first_name=John
id=123456789
username=johndoe

secret = SHA256("1234567890:ABCdefGHIjkl...")
hash = HMAC_SHA256(secret, data_check_string)

Luồng B: Web App

Dùng cho xác thực trong Telegram Mini App (WebApp).

Sequence diagram

Chi tiết HMAC verification (WebAppData)

Web App dùng key khác với Login Widget:

1. Lấy tất cả params từ initData trừ hash
2. Sắp xếp alphabetically, nối bằng \n
3. Tính secret = HMAC_SHA256("WebAppData", bot_token) — lưu ý key là string "WebAppData"
4. Tính expected = HMAC_SHA256(secret, data_check_string)
5. So sánh với hash

Khác biệt quan trọng: Login Widget dùng SHA256(bot_token) làm secret, Web App dùng HMAC_SHA256("WebAppData", bot_token).

So sánh hai luồng

Tiêu chí	Login Widget	Web App
Khi nào dùng	Web browser	Telegram Mini App
HTTP method	GET (redirect)	POST (AJAX)
HMAC key	SHA256(bot_token)	HMAC_SHA256("WebAppData", bot_token)
Data format	Query params	initData (query string in body)
Avatar	Không tải	Tải từ Bot API + lưu storage
Endpoint	telegram:redirect	telegram:validate
CORS	Bật	Bật

Avatar download (Web App only)

Trong Web App flow, nếu user có photo_url:

1. Server gọi Telegram Bot API với photo_url để tải ảnh
2. Lưu ảnh vào storage/uploads/
3. Cập nhật field avatar cho local user

Lưu ý: avatar chỉ tải trong Web App flow, Login Widget không tải avatar tự động.

Xử lý lỗi

Lỗi	Nguyên nhân	Giải pháp
HMAC mismatch	Bot token sai hoặc data bị tampering	Kiểm tra bot token
auth_date too old	Data quá cũ (Login Widget)	User thử lại đăng nhập
initData invalid	Mini App gửi sai format	Kiểm tra window.Telegram.WebApp.initData
Avatar download failed	Bot API không truy cập được	Kiểm tra kết nối internet từ server