LimboAuth: Velocity Proxy ile Minecraft Auth Sistemi Kurulumu — Eksiksiz Rehber

LimboAuth, Elytrium ekibi tarafından geliştirilen, Velocity proxy üzerinde çalışan bir Minecraft kimlik doğrulama (auth) eklentisidir. Oyuncuyu gerçek sunucuya göndermeden önce sanal bir limbo dünyasına alır, orada /register veya /login komutlarını tamamlatır, ardından lobby veya ana sunucuya aktarır. AuthMe'nin aksine yükün tamamı proxy katmanında karşılandığı için arka sunucular (Paper, Purpur, Folia) auth trafiğinden etkilenmez.

# LimboAuth Nedir?

LimboAuth, Elytrium'un Limbo ekosisteminin bir parçasıdır. Ekosistem üç ana bileşenden oluşur:

• LimboAPI: Velocity için sanal dünya (limbo) motoru. Paper/Spigot sunucusu olmadan bir chunk, oyuncu entity, blok ve inventory simülasyonu yapabilir. LimboAuth'un temel bağımlılığıdır.
• LimboAuth: Kimlik doğrulama, register/login, TOTP, captcha, session yönetimi ve veritabanı entegrasyonu.
• LimboFilter: Bot saldırılarına karşı ön filtre. IP hız sınırı, captcha, login attempt monitoring ve protokol seviyesi filtreleme sağlar — LimboAuth'tan önce devreye girer.

Bu rehberin ana odağı LimboAuth'tur, ancak üretimde üçünün birlikte kullanılması önerilir. Özellikle cracked (offline-mode) sunucular için LimboFilter + LimboAuth kombinasyonu standart bir koruma katmanıdır.

# Neden LimboAuth? — AuthMe ve LibreLogin ile Karşılaştırma

Minecraft ekosisteminde üç büyük auth çözümü vardır: AuthMe ReReloaded, LibreLogin ve LimboAuth. Seçim, sunucu mimarinize bağlıdır.

Özet karar: Yeni bir sunucu kuruyorsanız ve Velocity kullanıyorsanız LimboAuth; eski bir AuthMe kurulumunuz varsa ve taşınmak istiyorsanız LibreLogin (daha kolay migration path'i vardır); yalnızca tek bir Bukkit sunucusu çalıştırıyorsanız AuthMe ReReloaded.

# LimboAuth Nasıl Çalışır? — Mimari

Bir oyuncu Velocity'e bağlandığında süreç şöyle işler:

• 1. Bağlantı: Oyuncu Velocity'e handshake gönderir. Velocity oyuncuyu karşılar.
• 2. Premium kontrolü: Floodgate varsa Bedrock oyuncu tespit edilir. LimboAuth, Mojang API'ye sorgu atarak premium UUID'yi doğrular (force_offline_mode=false ise).
• 3. Limbo'ya yönlendirme: LimboAPI oyuncuyu sanal bir dünyaya yollar. Burada yalnızca chat ve sınırlı komutlar aktiftir.
• 4. Login/Register: Veritabanında kayıt varsa /login, yoksa /register istenir. Tamamlandığında token oluşur.
• 5. Aktarma: Oyuncu, try listesindeki ilk erişilebilir sunucuya (genellikle lobby) gönderilir.
• 6. Session: Belirli süre içinde tekrar bağlanırsa IP+UUID eşleşmesi ile otomatik giriş yapılır.

# Sistem Gereksinimleri

• Java: 17 veya üzeri (21 önerilir).
• Velocity: 3.3.0 veya üzeri (3.4+ daha stabil).
• RAM: LimboAPI + LimboAuth için ek 256–512 MB yeterli; bot saldırısı senaryosunda 1 GB ayırın.
• CPU: 1 vCPU LimboAuth için rahat yeter; LimboFilter'da captcha render varsa 2 vCPU önerilir.
• Veritabanı: H2 (test), MySQL 8.0+ / MariaDB 10.5+ (üretim), PostgreSQL 13+ (ölçek), SQLite (küçük ölçek).
• Disk: Auth verisi çok yer tutmaz; 100K kayıt ≈ 50 MB. MySQL için 1 GB ayırın.
• Proxy: Bağlantılar için açık portlar: 25565 (Minecraft), 3306 (MySQL, eğer harici ise).

# Kurulum: LimboAPI ve LimboAuth

İki eklentinin de Velocity'in plugins/ klasörüne atılması gerekir. LimboAuth, LimboAPI'ye bağımlıdır; sırayı şaşırırsanız Velocity başlangıçta hata verir.

# Velocity dizinine git
cd /opt/velocity

# LimboAPI indir (GitHub release sayfasından son sürüm)
wget -O plugins/limboapi.jar \
  https://github.com/Elytrium/LimboAPI/releases/latest/download/limboapi-plugin.jar

# LimboAuth indir
wget -O plugins/limboauth.jar \
  https://github.com/Elytrium/LimboAuth/releases/latest/download/limboauth.jar

# LimboFilter (opsiyonel ama önerilir)
wget -O plugins/limbofilter.jar \
  https://github.com/Elytrium/LimboFilter/releases/latest/download/limbofilter.jar

# Velocity'i yeniden başlat
systemctl restart velocity

İlk başlatmada LimboAuth, plugins/limboauth/ dizini altına config.yml, messages.yml ve varsayılan H2 veritabanı dosyasını oluşturur.

# Veritabanı Seçimi ve Kurulumu

LimboAuth dört veritabanı sürücüsü destekler: H2 (varsayılan, in-memory + disk), SQLite, MySQL/MariaDB ve PostgreSQL. Üretim için MySQL veya PostgreSQL tercih edin.

# MySQL / MariaDB Kurulumu

-- MySQL'de veritabanı ve kullanıcı oluştur
CREATE DATABASE limboauth CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'limboauth'@'localhost' IDENTIFIED BY 'GucluParola2026!';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX ON limboauth.* TO 'limboauth'@'localhost';
FLUSH PRIVILEGES;

config.yml içinde storage bloğunu aşağıdaki gibi güncelleyin:

database:
  storage-type: "mysql"
  hostname: "127.0.0.1:3306"
  user: "limboauth"
  password: "GucluParola2026!"
  database: "limboauth"
  connection-parameters: "?autoReconnect=true&useSSL=false&serverTimezone=UTC"

# PostgreSQL Kurulumu

sudo -u postgres psql
CREATE DATABASE limboauth;
CREATE USER limboauth WITH ENCRYPTED PASSWORD 'GucluParola2026!';
GRANT ALL PRIVILEGES ON DATABASE limboauth TO limboauth;
\q

# Temel Yapılandırma (config.yml)

İlk açılışta üretilen config.yml yüzlerce satırdır. Burada kritik parametreleri bölüm bölüm açıklıyoruz. Varsayılanı olduğu gibi kullanmak güvenlik açısından uygun değildir.

# Auth Bölümü

auth:
  # Minimum ve maksimum parola uzunluğu
  min-password-length: 8
  max-password-length: 100

  # Kayıt için parola iki kez istensin mi?
  enable-totp: true
  register-requires-repeat-password: true

  # Kayıt olmamış oyuncuya süre tanı (saniye)
  auth-time: 60

  # Kick eşiği (yanlış parola deneme)
  login-attempts: 3

  # IP başına kayıt sınırı (bot saldırılarına karşı)
  ip-limit-registrations: 3

  # Başka oyuncularla aynı nickname almak yasak
  save-uuid: true

  # Premium UUID'leri yanlış oyuncuların almasını engelle
  save-premium-accounts: true
  check-password-strength: true

# Main (Limbo Sunucu) Bölümü

main:
  # Limbo dünyasının sanal koordinatı — değiştirme gereği yok
  world-file-path: "worlds/world.schem"
  world-file-type: "WORLDEDIT_SCHEM"

  # Oyuncunun login sonrası yönlendirileceği sunucular
  auth-coords:
    x: 0.5
    y: 64
    z: 0.5
    yaw: 0
    pitch: 0

  # Login başarılı olunca hangi sunucuya aktarılacak?
  login-kick-message: "<red>Oturum süreniz doldu, tekrar giriş yapın."

# Premium (Online Mode) ve Cracked Ayrımı

Velocity'i offline-mode'da çalıştırıyorsanız (yani online-mode: false velocity.toml'da), LimboAuth Mojang API'ye sorgu atarak bu nick'in premium bir hesaba ait olup olmadığını kontrol edebilir. İki politika vardır:

• Strict mode (önerilen): Premium nickname'leri yalnızca premium oyuncular kullanabilir. Cracked oyuncu premium nick'e register olamaz.
• Free mode: Herkes her nick'i kullanabilir. Sadece premium oyuncular için auto-login avantajı.

auth:
  # Premium nickname'leri koru
  save-premium-accounts: true

  # Premium oyuncu register etmesin, doğrudan gelsin
  force-offline-uuid: false

  # Mojang API cache süresi (saniye)
  premium-check-cache: 3600

  # API erişilemezse ne yapılacak?
  # "ASSUME_CRACKED" güvenli default; "KICK" sıkı mod
  mojang-rate-limit-behavior: "ASSUME_CRACKED"

# TOTP / 2FA (Google Authenticator) Yapılandırması

LimboAuth RFC 6238 uyumlu TOTP desteği sunar. Oyuncu /2fa komutu ile QR kod veya 16 karakterli secret key alır, Google Authenticator / Authy / Microsoft Authenticator uygulamasına ekler.

auth:
  enable-totp: true
  totp-issuer: "KEYDAL Network"

  # TOTP zorunluluğu (admin grupları için önerilir)
  totp-need-passed-for-admins: true

  # Kod geçerlilik süresi
  totp-recovery-codes-amount: 16

• /2fa — TOTP'yi aktifleştirir, QR kod verir
• /2fa disable [parola] — 2FA'yi kaldırır
• /2fa recovery — 16 kurtarma kodu üretir, ekran görüntüsü alması önerilir

# Captcha Yapılandırması

Bot saldırılarına karşı LimboFilter ile entegre captcha sistemi. Oyuncu limbo'da iken harita üzerinde çıkan 5 haneli rakamı /captcha [kod] şeklinde girer.

captcha:
  # Captcha zorla (önerilen)
  need-captcha: true

  # IP başına günde kaç captcha?
  ip-captcha-limit: 10

  # Captcha süresi (saniye)
  captcha-duration: 30

  # Yanlış cevap sonrası yeni captcha üretilsin mi?
  regen-on-wrong: true

  # Görsel kalite
  captcha-length: 5
  render-font: "DroidSansMono"

# E-posta ile Parola Sıfırlama

LimboAuth JavaMail üzerinden SMTP entegrasyonu yapar. Bu özelliği aktif etmeden oyuncular /forgotpassword komutunu kullanamaz.

email:
  enable-email: true
  smtp-host: "smtp.gmail.com"
  smtp-port: 587
  smtp-username: "noreply@keydal.tr"
  smtp-password: "app-specific-password"
  smtp-ssl: false
  smtp-starttls: true

  from-name: "KEYDAL Minecraft"
  from-email: "noreply@keydal.tr"

  subject: "Parola Sıfırlama Kodu"
  text: "Merhaba {USER}, kodunuz: {CODE}"

  # Kod geçerlilik süresi (dakika)
  code-expire-time: 15

# Session Yönetimi

Aynı IP'den gelen oyuncuya belirli süre içinde tekrar login sormadan giriş izni vermek için session sistemi kullanılır.

session:
  # Session aktif
  remember-session: true

  # Session süresi (saniye, 3600 = 1 saat)
  session-duration: 86400

  # IP değişirse session düşsün mü?
  kick-on-ip-change: true

  # Session bilgisi nerede saklanacak?
  # memory (restart'ta silinir) veya database (kalıcı)
  session-storage: "database"

# LimboAuth Komutları ve İzinleri

Oyuncu tarafı ve admin tarafı komutları ayrı izinlerle kontrol edilir. LuckPerms ile grup bazlı izin vermek en sağlıklı yoldur.

# Oyuncu Komutları

# Admin Komutları ve İzinler

• /limboauth reload — limboauth.admin.reload
• /limboauth forcechangepassword [oyuncu] [yeni] — limboauth.admin.forcechangepassword
• /limboauth unregister [oyuncu] — limboauth.admin.unregister
• /limboauth premium [oyuncu] — oyuncuyu premium olarak işaretler, parola istemez
• /limboauth forceregister [oyuncu] [parola] — oyuncu yokken kayıt açar

# LimboFilter ile Birlikte Kullanım

LimboFilter, LimboAuth'tan önce devreye giren bir bot filtresidir. Oyuncu handshake attığında önce LimboFilter'a düşer, protokol seviyesinde kontrol edilir (chat filter, CPS check, position check), ardından LimboAuth'a aktarılır.

# plugins/limbofilter/config.yml
filter:
  # Hangi durumda filter devreye girecek?
  # ALWAYS (her zaman), ON_ATTACK (saldırı tespit edilince)
  filter-mode: "ON_ATTACK"

  # Saldırı eşiği (saniyede bağlanma)
  cps-threshold: 20

  # Rate limit
  max-connections-per-ip: 3
  connection-limit-seconds: 10

  # Captcha limbofilter'da da aktif
  captcha: true
  chat-filter: true
  position-check: true

# Performans ve Optimizasyon

• JVM flags: Velocity için Aikar flags kullanın. -Xms2G -Xmx2G -XX:+UseG1GC baseline; LimboAPI+LimboAuth yükü genelde az.
• Connection pool: MySQL'de HikariCP pool size 10–20 arasında kalsın. Yüksek tutmak CPU'yu yer, düşük tutmak login bekletir.
• H2 kullanıyorsanız: Üretimde kullanmayın. 10K+ kayıtta corruption riski var, crash recovery yavaş.
• LimboAPI tick rate: simulation-distance: 4 olarak düşürün; limbo'da render gerektirmeyen boş bir dünya zaten.
• Async logging: Velocity'nin velocity.toml'inde announce-forge: false ve kick-existing-players: true.
• Mojang API cache: premium-check-cache en az 3600 (1 saat); saldırı zamanı Mojang rate limit atarsa tüm login'ler düşer.

# Yaygın Sorunlar ve Çözümleri

# Sorun 1: Oyuncu Limbo'ya Düşüp Chat Yazamıyor

Velocity'nin player-info-forwarding-mode ayarı yanlış. BungeeCord'dan gelenler için legacy, modern Paper sunucuları için modern olmalı. Arka sunucularda da paper-global.yml içinde velocity-support: true ve secret eşleşmeli.

# Sorun 2: TOTP Kodu Her Seferinde Yanlış Diyor

Sunucu saati NTP ile senkron değil. TOTP 30 saniyelik slice kullanır; sunucu saati telefondan 30s+ saparsa kod yanlış görünür. timedatectl set-ntp true ile düzeltin.

# Sorun 3: MySQL Connection Timeout

connection-parameters içine &autoReconnect=true&tcpKeepAlive=true ekleyin. HikariCP default timeout 30s; uzun süre idle bağlantılar düşebilir. maxLifetime: 1800000 (30 dakika) ile MySQL'in wait_timeout değerinden küçük tutun.

# Sorun 4: Oyuncu 'Premium' Diye Gösterilmesine Rağmen Parola İsteniyor

force-offline-uuid: true ayarlanmış demektir. Bu durumda LimboAuth premium bypass yapmaz. false'a çekin ve save-premium-accounts: true aktif olsun. Mojang API'ye erişim var mı kontrol edin: curl https://api.mojang.com/users/profiles/minecraft/Notch.

# Sorun 5: Veritabanı Migration Sırasında Hata

Yeni sürüme geçerken LimboAuth, şema migration'ı otomatik yapmaya çalışır. Eğer başarısız olursa ~/.limboauth-backups/ altına yedek alınır. Manuel migration için sürüm notlarındaki SQL script'lerini sırayla uygulayın.

# Sorun 6: Çok Fazla 'Failed to check premium status' Uyarısı

Mojang API rate limit'e yakalanmışsınız. Mojang sunucuları dakikada ≈ 600 istek kabul eder. Cache süresini artırın (premium-check-cache: 7200), paralel kuyruğu düşürün (mojang-rate-limit-max-parallel: 5).

# Güvenlik Best Practices

• BCrypt cost artırın: Default 10; modern CPU'larda 12 önerilir. auth.bcrypt-cost: 12. Her +1 cost login süresini 2x yapar.
• Admin hesaplarına TOTP zorunlu: totp-need-passed-for-admins: true + LuckPerms permission.
• Config dosyası izinleri: chmod 600 plugins/limboauth/config.yml. root veya velocity user'ı dışında kimse okuyamasın.
• MySQL bağlantısı localhost: Veritabanı TCP port 3306'yı dışarıya açmayın. bind-address = 127.0.0.1.
• TLS önerilir: Proxy ile DB farklı sunucuda ise SSL/TLS bağlantı zorunlu. useSSL=true&requireSSL=true.
• Düzenli yedek: mysqldump ile günlük yedek alın; hesap database'i kaybolursa tüm oyuncu kaydı gider.
• Velocity'de proxy secret: forwarding.secret rastgele 32 karakterli string olsun; arka sunucu paper-global.yml'de aynı secret eşleşsin.

# Gerçek Üretim Yapılandırma Örneği

Aşağıdaki config.yml, KEYDAL olarak kurduğumuz production Velocity network'lerinde kullandığımız şablondur. 500+ eşzamanlı oyuncu yükünde test edilmiştir.

# plugins/limboauth/config.yml — production template
auth:
  min-password-length: 8
  max-password-length: 100
  auth-time: 60
  login-attempts: 3
  ip-limit-registrations: 3

  save-uuid: true
  save-premium-accounts: true
  force-offline-uuid: false
  check-password-strength: true

  enable-totp: true
  totp-issuer: "KEYDAL Network"
  totp-need-passed-for-admins: true
  totp-recovery-codes-amount: 16

  premium-check-cache: 7200
  mojang-rate-limit-behavior: "ASSUME_CRACKED"
  mojang-rate-limit-max-parallel: 10

  bcrypt-cost: 12

database:
  storage-type: "mysql"
  hostname: "127.0.0.1:3306"
  user: "limboauth"
  password: "${LIMBOAUTH_DB_PASS}"
  database: "limboauth"
  connection-parameters: "?autoReconnect=true&tcpKeepAlive=true&useSSL=false&serverTimezone=UTC&characterEncoding=utf8"

  hikari:
    maximum-pool-size: 15
    minimum-idle: 5
    connection-timeout: 10000
    idle-timeout: 600000
    max-lifetime: 1700000

captcha:
  need-captcha: true
  ip-captcha-limit: 15
  captcha-duration: 30
  regen-on-wrong: true
  captcha-length: 5

session:
  remember-session: true
  session-duration: 86400
  kick-on-ip-change: false
  session-storage: "database"

email:
  enable-email: true
  smtp-host: "smtp.sendgrid.net"
  smtp-port: 587
  smtp-starttls: true
  from-name: "KEYDAL Minecraft"
  from-email: "noreply@keydal.tr"
  code-expire-time: 15

# AuthMe'den LimboAuth'a Geçiş

Mevcut bir AuthMe ReReloaded kurulumunuz varsa LimboAuth'a geçiş mümkündür. Parola hash'leri (BCrypt) uyumlu olduğu için kullanıcılar parolalarını yeniden girmez. Adımlar:

• 1. AuthMe'nin authme MySQL tablosunu yedekle: mysqldump authme authme_users > authme.sql
• 2. LimboAuth'u kur, schema oluştursun (ilk çalıştırma).
• 3. Migration SQL çalıştır:
• INSERT INTO limboauth_auth (lower_nickname, nickname, hash, ip, premium_uuid, reg_date, login_date) SELECT LOWER(username), realname, password, ip, NULL, regdate, lastlogin FROM authme_users;
• 4. Hash tipini LimboAuth'ta doğrula: AuthMe'nin 'BCRYPT' hash'leri direkt geçer, 'SHA256' için extra adım gerek.
• 5. AuthMe plugin'ini kaldır, Velocity'i yeniden başlat.

# Sık Sorulan Sorular

# LimboAuth ücretsiz mi?

Evet, tamamen açık kaynak (MIT lisansı) ve ücretsizdir. Ticari kullanımda kısıtlama yoktur.

# 1.8 istemcisi desteği var mı?

LimboAPI ile birlikte 1.7.x'ten 1.21.x'e kadar tüm Minecraft protokollerini destekler. ViaVersion / ViaBackwards kurulumuna gerek yoktur (LimboAPI içinde entegre).

# Bedrock (Floodgate) oyuncular da auth olmak zorunda mı?

Floodgate ile gelen Bedrock oyuncular Microsoft tarafından zaten auth edilmiş sayılır. auth.floodgate-need-auth: false ile Bedrock oyuncuları auth'tan muaf tutabilirsiniz.

# Veritabanı başka bir sunucuda olabilir mi?

Evet, uzak MySQL/PostgreSQL desteklenir. Ancak gecikme (latency) çok önemli — ağır login yükünde proxy ile DB arasında 5ms+ RTT varsa TPS'e etki eder. DB'yi proxy ile aynı DC'de tutun, TLS kullanın.

# Bot saldırısına karşı yeterli mi?

LimboAuth tek başına temel koruma sağlar. Ciddi DDoS/bot saldırıları için LimboFilter + Cloudflare Spectrum (TCP proxy) veya KEYDAL DDoS korumalı VPS paketleri önerilir.

# GeyserMC ile uyumlu mu?

Evet, tam uyumlu. Geyser + Floodgate yapılandırması LimboAuth ile sorunsuz çalışır. Bedrock oyuncular için bedrock.require-register: false önerilir (Microsoft auth zaten vardır).

# Kaynaklar ve Resmi Dokümantasyon

LimboAuth, LimboAPI ve LimboFilter projeleri Elytrium ekibi tarafından aktif geliştirilir. Güncel sürüm, hata raporu ve detaylı API dokümantasyonu için birinci el kaynaklar:

• LimboAuth — GitHub reposu
• LimboAPI — GitHub reposu
• LimboFilter — GitHub reposu
• LimboAuth — Modrinth sayfası
• LimboAuth Wiki — resmi dokümantasyon
• Velocity Proxy — resmi sitesi
• Velocity Docs — başlangıç rehberi
• AuthMe ReReloaded — GitHub (karşılaştırma için)
• LibreLogin — GitHub (karşılaştırma için)
• LuckPerms — permission plugin entegrasyonu
• RFC 6238 — TOTP standardı (teknik referans)

# KEYDAL İçinde İlgili Rehberler

• Velocity Proxy ile Network Kurulumu
• BungeeCord Network Kurulumu
• LuckPerms Yetki Yönetimi Rehberi
• Minecraft Anti-Cheat Sistemi Rehberi
• En Popüler 100 Minecraft Plugin (2026)