Skip to content

README.md

Latest commit

 

History

History
168 lines (122 loc) · 4.61 KB

README.md

File metadata and controls

168 lines (122 loc) · 4.61 KB
Raw

Minecraft Authserver

Minecraft-compatible authentication and session server (Yggdrasil-style API). Used by custom launchers and game servers for offline or self-hosted auth.

Features

  • Account authentication (/authenticate, /refresh)
  • Minecraft session API (/session/minecraft/*)
  • Profiles and textures (/texture, bulk lookup)
  • RSA keys for session verification (/publickeys)
  • Account storage: MySQL or SleekDB (file-based)
  • Password hashing: phpass (default) or MD5
  • CLI for account and certificate management

Stack

  • PHP 7.3, Flight micro-framework
  • Symfony Console (CLI)
  • PHP-DI, nginx + php-fpm (Docker)
  • MailHog for dev email capture

Quick start (Docker)

docker compose up -d

HTTP is available on port 8187 by default; MailHog UI on 8175.

Health check:

curl -s -o /dev/null -w "%{http_code}" http://localhost:8187/
# 200

Session keys (first-time setup)

RSA session keys are required before the server can sign player textures or serve /publickeys. Generate them once on a fresh install.

Docker:

docker compose up -d
docker compose exec cli php bin/console certificates:generate

Without Docker:

cd authserver
composer install
php bin/console certificates:generate

The command writes three files to authserver/var/certificates/ (override via certificatesDir in config.php):

File Purpose
yggdrasil_session_private.pem Signs texture properties (Authenticator)
yggdrasil_session_public.pem Served by GET /publickeys
yggdrasil_session_pubkey.jar Trust anchor for Java/Minecraft clients (yggdrasil_session_pubkey.der inside)

The command refuses to overwrite an existing private key. Delete the files manually only if you intend to rotate keys (existing clients must be updated with the new public key).

Verify the keys are loaded:

curl -s http://localhost:8187/publickeys | python3 -m json.tool

Expected: JSON with profilePropertyKeys and playerCertificateKeys, each containing a publicKey field.

Configuration

Copy the example and adjust for your environment:

cp authserver/config.example.mysql.php authserver/config.php

Key options in config.php:

Key Values Description
account.storage mysql, sleekdb Account storage backend
account.hash_algorithm default, md5 Password hash algorithm
account.mysql.* — DSN, table, column mapping
account.sleekdb.* — Data directory and cache TTL
certificatesDir var/certificates RSA key output directory
skinDir var/skins Local skin files root

HTTP API

Method Path Purpose
GET / Health check
POST /authenticate Login with username/password
POST /refresh Refresh access token
GET /publickeys Public RSA keys
GET /texture/@hash Texture by hash
POST /session/minecraft/join Register server session
GET /session/minecraft/hasJoined Server session verification
GET /session/minecraft/profile/@profile Player profile
POST /minecraft/profile/lookup/bulk/byname Bulk profile lookup

Document root: authserver/public/index.php.

CLI

Run commands inside the cli container:

docker compose exec cli php bin/console list
Command Description
account:create Create account
account:find Find account
account:delete Delete account
account:authenticate Verify credentials
certificates:generate Generate RSA certificates
session:server-join Simulate server join
session:server-has-joined Simulate hasJoined

Example:

docker compose exec cli php bin/console account:create Steve steve@example.com secret

Project layout

authserver/          # PHP application
  bin/console        # CLI entrypoint
  public/            # Web entrypoint
  src/               # Source code
  var/               # Data, skins, certificates
docker/              # nginx, php-fpm config
docker-compose.yml

Development without Docker

cd authserver
composer install
cp config.example.mysql.php config.php
# edit config.php
php -S localhost:8080 -t public

Docker environment variables

Variable Default Description
DOCKER_PORT_HTTP 8187 nginx HTTP port
DOCKER_PORT_MAIL_HTTP 8175 MailHog web UI

License

MIT — see authserver/composer.json.

For AI agents

Agent instructions (Cursor, Claude, etc.): AGENTS.md.