BeaconAuth

Mod installation

Install and configure the BeaconAuth Minecraft mod.

Server installation

  1. 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
  2. Place the jar in the server mods/ directory.
  3. Restart the server.

Client installation

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

Supported versions

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

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)

  1. Enable behavior.use_legacy_offline_uuids = true and keep the server in offline-mode.
  2. 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.
  3. 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.
  4. 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.
  5. Rescue path for mistakes: a server operator (permission level 2) can transfer an identity with /beaconauth transfer-identity <minecraftName> <beaconUsername>.
  6. 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).

Premium players on a migrated server (linked Minecraft accounts)

When some of your migrated players are actually premium (they own a real Minecraft account), you can let them keep using their migrated world data without a web login:

  1. In the BeaconAuth web UI, players link their Minecraft account (Microsoft/Xbox sign-in) and set their identity preference to Legacy offline identity (preserve world data).
  2. On the server, set behavior.minecraft_lookup_secret to the shared secret you configured on the BeaconAuth server (MINECRAFT_LOOKUP_SECRET).
  3. When a Mojang-verified premium player joins (online-mode bypass), the mod asks the BeaconAuth server whether that Mojang UUID is bound to an account with the "legacy" preference. If yes, the player is mapped to the legacy offline UUID the account owns on this world, and the cached Mojang textures property is replayed, so they keep their world data and their real skin/cape.

Notes:

  • The lookup only ever answers "is this Mojang UUID bound, and how should the mod resolve its identity" — it does not expose any private data.
  • If the identity preference is "Mojang UUID" (the default) or the UUID is not bound, the premium player simply keeps the Mojang UUID (vanilla behavior).
  • If the player's legacy offline identity is already claimed by another BeaconAuth account, the premium player keeps the Mojang UUID and a warning is logged (never silently override).
  • resolve_linked_premium_legacy = false disables this resolution even when a secret is set.

On this page

Server installationClient installationSupported versionsMod configurationNotesMigrating an existing offline-mode server (legacy identities)Premium players on a migrated server (linked Minecraft accounts)