TgAuth — Telegram Authentication
仅服务端。 玩家每次登录时通过 Telegram 进行身份验证。无需客户端模组。
工作原理
新玩家 — 首次设置
- 玩家打开 Telegram → 向机器人发送
/start
- 机器人检查白名单 → 生成一个 6 位验证码
- 玩家加入服务器 → 输入
/tgauth link <code>
- 账号永久绑定到其 Telegram
老玩家 — 每次登录
加入服务器
│
▼
与上次使用同一设备吗?(基于 IP 的会话,有效期 12 小时)
├── 是 → 自动登录,无需 Telegram ✅
└── 否 → 机器人向 Telegram 发送确认请求:
[✅ 是] [❌ 否]
│ │
登录成功 ✅ 被踢出 ❌
功能特性
- ? 每次登录需 Telegram 确认 — 新设备需要授权
- ? 12 小时设备会话 — 同一 IP 在会话窗口内无需提示
- ? 按 Telegram ID 白名单管理 — 仅允许已批准用户注册
- ? 内联键盘按钮 — 直接在 Telegram 聊天中点击“是/否”
- ⏱ 可配置超时时间 — N 秒内无响应则踢出
- ? 管理员命令 — 管理白名单、强制批准、清除会话
- ? 持久化数据 — 链接信息在服务重启后依然保留(
world/data/tgauth_players.json)
安装设置
1. 创建 Telegram 机器人
打开 @BotFather → 发送 /newbot → 复制生成的 token。
2. 获取玩家的 Telegram ID
每位玩家需要向 @userinfobot 发送消息 → 复制其 Id。
3. 配置 config/tgauth-server.toml
[bot]
botToken = "1234567890:AAH..."
botUsername = "MyServerAuthBot"
[whitelist]
telegramIds = ["123456789", "987654321"]
[session]
durationHours = 12
4. 重启服务器。 完成。
指令
玩家
| 指令 |
说明 |
/tgauth link <code> |
绑定 Telegram 账号(新玩家) |
/tgauth status |
显示绑定状态和活跃会话 |
操作员 (OP 2+)
| 指令 |
说明 |
/tgauth admin whitelist list |
列出所有已列入白名单的 Telegram ID |
/tgauth admin whitelist add <id> |
添加一个 Telegram ID |
/tgauth admin whitelist remove <id> |
移除一个 Telegram ID |
/tgauth admin unlink <player> |
解除玩家的 Telegram 绑定 |
/tgauth admin force <player> |
强制批准待处理的登录请求 |
/tgauth admin sessions <player> |
显示该玩家活跃的设备会话 |
/tgauth admin clearsessions <player> |
使该玩家的所有设备会话失效 |
/tgauth admin reload |
从配置文件重新加载白名单 |
兼容性
|
|
| Minecraft |
1.21.1 |
| Loader |
NeoForge |
| Side |
仅服务端 |
| Java |
21+ |
常见问题
玩家可以在同一个网络下吗?
可以。指纹由 IP + UUID 组合而成,因此来自同一 NAT 的两个玩家会有不同的指纹。
如果玩家使用了 VPN 会怎样?
IP 地址改变 → 会话失效 → 下次登录时需要 Telegram 确认。
离线模式服务器可以使用吗?
可以,匹配是基于 UUID 进行的,NeoForge 在线模式和离线模式下均提供 UUID。
机器人 Token 存储安全吗?
它保存在你服务器的 config/tgauth-server.toml 文件中——请确保该文件私密存放。
TgAuth — Telegram Authentication
Server-side only. Players authenticate via Telegram on every login. No client mod needed.
How it works
New player — first time setup
- Player opens Telegram → sends
/start to the bot
- Bot checks the whitelist → issues a 6-digit code
- Player joins the server → types
/tgauth link <code>
- Account is permanently linked to their Telegram
Returning player — every login
Join server
│
▼
Same device as last time? (IP-based session, valid 12 hours)
├── YES → Auto login, no Telegram needed ✅
└── NO → Bot sends confirmation to Telegram:
[✅ Yes] [❌ No]
│ │
Logged in ✅ Kicked ❌
Features
- ? Per-login Telegram confirmation — every new device requires approval
- ? 12-hour device sessions — same IP = no prompt within the session window
- ? Whitelist by Telegram ID — only approved users can register
- ? Inline keyboard buttons — Yes/No directly in Telegram chat
- ⏱ Configurable timeout — kick if no response within N seconds
- ? Admin commands — manage whitelist, force-approve, clear sessions
- ? Persistent data — links survive server restarts (
world/data/tgauth_players.json)
Setup
1. Create a Telegram bot
Open @BotFather → /newbot → copy the token.
2. Get Telegram IDs of your players
Each player writes to @userinfobot → copies their Id.
3. Configure config/tgauth-server.toml
[bot]
botToken = "1234567890:AAH..."
botUsername = "MyServerAuthBot"
[whitelist]
telegramIds = ["123456789", "987654321"]
[session]
durationHours = 12
4. Restart the server. Done.
Commands
Players
| Command |
Description |
/tgauth link <code> |
Link Telegram account (new players) |
/tgauth status |
Show link status and active session |
Operators (OP 2+)
| Command |
Description |
/tgauth admin whitelist list |
List all whitelisted Telegram IDs |
/tgauth admin whitelist add <id> |
Add a Telegram ID |
/tgauth admin whitelist remove <id> |
Remove a Telegram ID |
/tgauth admin unlink <player> |
Unlink a player's Telegram account |
/tgauth admin force <player> |
Force-approve a pending login |
/tgauth admin sessions <player> |
Show active device sessions |
/tgauth admin clearsessions <player> |
Invalidate all device sessions |
/tgauth admin reload |
Reload whitelist from config |
Compatibility
|
|
| Minecraft |
1.21.1 |
| Loader |
NeoForge |
| Side |
Server only |
| Java |
21+ |
FAQ
Can players be on the same network?
Yes. The fingerprint combines IP + UUID, so two players from the same NAT have different fingerprints.
What happens if a player uses a VPN?
Their IP changes → session invalidated → Telegram confirmation required on next login.
Does this work with offline mode servers?
Yes, matching is done by UUID which NeoForge provides in both online and offline mode.
Is the bot token stored securely?
It lives in config/tgauth-server.toml on your server — keep that file private.
评论 0
登录后参与评分
还没有评论,来抢沙发吧