TgAuth2

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

- 🔐 Persistent data — every new device requires approval - 💾 Persistent data — same IP = no prompt within the session window - 📋 Persistent data — only approved users can register - 🤖 Persistent data — Yes/No directly in Telegram chat - ⏱ Persistent data — kick if no response within N seconds - 🔧 Persistent data — 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`

```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

| | | |---|---| | Java | 1.21.1 | | Java | NeoForge | | Java | 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.