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

1. Player opens Telegram → sends /start to the bot
2. Bot checks the whitelist → issues a 6-digit code
3. Player joins the server → types /tgauth link <code>
4. 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.