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

Operators (OP 2+)

Compatibility

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.