Giao diện

Hướng dẫn cài đặt Telegram Auth ​

Hướng dẫn thiết lập xác thực Telegram Login trong Digiforce, bao gồm tạo bot và cấu hình Login Widget.

Điều kiện tiên quyết ​

  • Digiforce đã cài đặt và chạy ổn định
  • Plugin @digiforce-nc/plugin-auth-telegram đã được kích hoạt
  • Tài khoản Telegram

Bước 1: Tạo Telegram Bot ​

  1. Mở Telegram, tìm @BotFather
  2. Gửi lệnh /newbot
  3. Đặt tên bot (ví dụ: Digiforce Login Bot)
  4. Đặt username bot (ví dụ: digiforce_login_bot) — phải kết thúc bằng bot
  5. BotFather trả về Bot Token — sao chép và lưu lại
Done! Congratulations on your new bot.
Use this token to access the HTTP Bot API:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Cấu hình domain cho Login Widget ​

  1. Gửi lệnh /setdomain cho BotFather
  2. Chọn bot vừa tạo
  3. Nhập domain Digiforce (ví dụ: app.example.com) — không có https://

Quan trọng

Domain phải được đăng ký với BotFather để Login Widget hoạt động. Nếu thiếu bước này, widget sẽ không hiển thị hoặc báo lỗi domain.

Bước 2: Tạo authenticator trong Digiforce ​

  1. Vào Settings → Authentication → Add new
  2. Chọn loại Telegram
  3. Đặt tên authenticator (ví dụ: telegram-login)
  4. Điền thông số:
TrườngGiá trị
Bot UsernameUsername bot (không có @). Ví dụ: digiforce_login_bot
Bot TokenToken từ BotFather
  1. Bật/tắt Auto Signup tùy nhu cầu

Bước 3: Kiểm tra đăng nhập (Login Widget) ​

  1. Mở trang đăng nhập Digiforce trên trình duyệt
  2. Nhấn nút Đăng nhập bằng Telegram
  3. Telegram hiển thị popup yêu cầu xác nhận
  4. Xác nhận → quay về Digiforce với session

Bước 4: Web App flow (tùy chọn) ​

Nếu sử dụng Telegram Mini App (WebApp):

  1. Tạo Mini App trong BotFather (lệnh /newapp)
  2. Gọi API telegram:validate từ Mini App với window.Telegram.WebApp.initData
  3. Server verify HMAC và tạo session

Lưu ý ​

  • CORS: Plugin tự động bật CORS cho cả hai endpoint (telegram:redirect và telegram:validate)
  • HTTPS: Login Widget yêu cầu domain chạy trên HTTPS
  • Bot Token bảo mật: Bot Token chỉ lưu server-side (telegram.botToken), không expose ra client
  • Avatar: Web App flow hỗ trợ tải avatar user từ Telegram và lưu vào storage