Tham số cấu hình Telegram Auth

Tài liệu chi tiết tất cả tham số cấu hình của plugin @digiforce-nc/plugin-auth-telegram.

Tham số public (client-side)

Tham số	Kiểu	Mặc định	Mô tả
`public.botUsername`	`string`	—	Username của Telegram bot (không có `@`). Dùng cho Login Widget trên trang đăng nhập. Ví dụ: `digiforce_login_bot`
`public.autoSignup`	`boolean`	`true`	Tự động tạo tài khoản local nếu Telegram user chưa có tài khoản trong Digiforce

Tham số server-side

Tham số	Kiểu	Mặc định	Mô tả
`telegram.botToken`	`string`	—	Bot Token từ @BotFather. Bắt buộc. Chỉ lưu server-side, không expose ra client. Dùng để: (1) tính HMAC verify, (2) gọi Bot API tải avatar
`telegram.http`	`boolean`	`false`	Dùng HTTP thay HTTPS cho redirect URL. Chỉ bật khi phát triển local
`telegram.port`	`string`	—	Port tùy chỉnh cho redirect URL. Hữu ích khi chạy sau reverse proxy

Phân biệt public vs server-side

public.*: gửi cho client (browser) — chỉ chứa thông tin không nhạy cảm
telegram.*: chỉ giữ server-side — chứa bot token (bảo mật)

CORS

Plugin tự động bật CORS cho hai endpoint:

telegram:redirect (Login Widget callback)
telegram:validate (Web App validation)

Điều này cần thiết vì:

Login Widget chạy trong iframe Telegram trên domain khác
Mini App gọi API từ Telegram WebView

Không cần cấu hình CORS riêng cho hai endpoint này.

HMAC Verification keys

Plugin sử dụng telegram.botToken để tính HMAC verify, với key khác nhau cho mỗi flow:

secret_key = SHA256(bot_token)

Web App

secret_key = HMAC_SHA256("WebAppData", bot_token)

Không cần cấu hình riêng — plugin tự động chọn key dựa trên endpoint được gọi.

Ví dụ cấu hình

json

{
  "public": {
    "botUsername": "digiforce_login_bot",
    "autoSignup": true
  },
  "telegram": {
    "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
    "http": false
  }
}

Ví dụ cấu hình phát triển local

json

{
  "public": {
    "botUsername": "digiforce_dev_bot",
    "autoSignup": true
  },
  "telegram": {
    "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
    "http": true,
    "port": "13000"
  }
}

So sánh tham số với OIDC

Tiêu chí	Telegram	OIDC
Số tham số	5	15+
Cần client secret	Không (dùng bot token)	Có
Redirect URI config	`http` + `port`	`http` + `port`
User binding	Telegram ID (tự động)	`userBindField` (email/username)
Certificate	Không	Có thể (skipSSLVerification)

Telegram Auth có cấu hình đơn giản — chỉ cần bot token và username.