BeaconAuth

Server installation

Download the matching mod jar from the file page on the platform where you found BeaconAuth.
- CurseForge: use the Files tab and choose the jar matching your Minecraft version and loader.
- Modrinth: use the Versions tab and choose the jar matching your Minecraft version and loader.
- Fabric: beaconauth-fabric-*.jar
- Forge: beaconauth-forge-*.jar
- NeoForge: beaconauth-neoforge-*.jar
Place the jar in the server mods/ directory.
Restart the server.

Client installation

Download the same mod jar as the server from the same release platform.
Place it in the client mods/ directory.
Launch the game and authenticate when prompted.

Supported versions

The repository ships loaders for Minecraft 1.19.2, 1.20.1, 1.21.1, 1.21.8, and 26.2 (see modSrc/). Minecraft 26.2 requires Java 25.

Mod configuration

After the first server startup, a configuration file is generated at:

config/beaconauth-server.toml

Example configuration:

[authentication]
# Base URL of your authentication server
# Example: https://beaconauth.pages.dev (development) or https://auth.example.com (production)
# WARNING: Always use HTTPS in production!
base_url = "https://beaconauth.pages.dev"

# JWKS (JSON Web Key Set) URL for JWT signature verification (fallback)
# Usually: <base_url>/.well-known/jwks.json
# Empty means: derive from base_url
jwks_url = ""

[jwt]
# Expected JWT audience (aud claim)
audience = "minecraft-client"

[jku]
# JWT JWKS Discovery (JKU)
# If allowed_host_patterns is non-empty and the JWT has a 'jku' header, BeaconAuth will fetch keys from that JWKS URL.
# Security: You MUST restrict allowed hosts to avoid SSRF.
# When enabled, JKU ALWAYS requires https://.
# Empty means: JKU disabled (BeaconAuth will ignore token 'jku' and only use authentication.jwks_url).
allowed_host_patterns = "beaconauth.pages.dev, *.beaconauth.pages.dev"

[behavior]
# Online-mode (recommended true):
# - Premium players can join without BeaconAuth web login and keep their Mojang UUID
#   (including vanilla clients without this mod).
# - Offline/community players with this mod can still join via BeaconAuth web login.
# If false: every player must use BeaconAuth (vanilla clients without the mod are rejected).
bypass_if_online_mode_verified = true
# If true: Modded clients MUST authenticate when server is offline-mode
force_auth_if_offline_mode = true
# Only applies when force_auth_if_offline_mode is true
# If true: offline-mode vanilla clients (without BeaconAuth mod) are allowed in.
allow_vanilla_offline_clients = true
# Legacy offline identity mode (for migrating an existing offline-mode server):
# - If true: each BeaconAuth account is mapped to the offline-mode UUID ("OfflinePlayer:<name>")
#   it claimed on its first authenticated login, and keeps that identity afterwards.
# - World data (playerdata/, stats/, advancements/) is preserved without renaming files.
# - The mapping is stored per-world in <world>/beaconauth-identities.json.
# - Security: the identity is bound to the username used on first login, so another account
#   registering the same username later would map to the same UUID. Intended for small servers.
use_legacy_offline_uuids = false
# If a Mojang-verified (premium) player is bound to a BeaconAuth account and their identity
# preference is "legacy", map them back to the legacy offline UUID on online-mode bypass so
# world data is preserved. Requires the lookup secret below.
# Leave empty (default) to keep premium players on the Mojang UUID.
minecraft_lookup_secret = ""
# Only meaningful when minecraft_lookup_secret is set: enable the linked-premium legacy
# resolution on online-mode bypass. Recommended true.
resolve_linked_premium_legacy = true

Notes

authentication.base_url is used for building login URLs and the expected JWT issuer (iss).
authentication.jwks_url defaults to ${base_url}/.well-known/jwks.json when empty.
jku.allowed_host_patterns is a comma/space separated allowlist. Supported patterns:
- example.com, *.example.com
- Not supported: bare * or mid-string wildcards like auth*.example.com
With the default behavior settings on an online-mode server, premium accounts join like vanilla multiplayer; offline accounts need the BeaconAuth mod and web login.

Migrating an existing offline-mode server (legacy identities)

Enable behavior.use_legacy_offline_uuids = true and keep the server in offline-mode.
On each player's first BeaconAuth login, the mod binds that account to the offline UUID (OfflinePlayer:<name>) and writes <world>/beaconauth-identities.json, so existing playerdata/, stats/, and advancements/ keep working without renaming files.
To plan the migration, run /beaconauth unmigrated (permission level 2). It lists every offline profile in playerdata/ that no BeaconAuth account has claimed yet, with the player name when available; the server also logs the total count on startup.
A legacy identity can only ever be claimed once: if another BeaconAuth account later tries to log in with the same in-game name, login is rejected with a clear message instead of silently binding the identity.
Rescue path for mistakes: a server operator (permission level 2) can transfer an identity with /beaconauth transfer-identity <minecraftName> <beaconUsername>.
Once everyone is migrated, the mapping keeps working; turning the mode off later switches accounts back to stable per-account UUIDs (new world data, not the legacy data).

Mod installation