Mod installation
Install and configure the BeaconAuth Minecraft mod.
Server installation
- Download the latest mod jar from GitHub Releases.
- Latest release: GitHub Releases (latest)
- 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.
- Latest release: GitHub Releases (latest)
- Place it in the client
mods/directory. - Launch the game and authenticate when prompted.
Supported versions
The repository ships loaders for Minecraft 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]
# If true: Players with valid Mojang accounts skip BeaconAuth when server is in online-mode
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
allow_vanilla_offline_clients = falseNotes
authentication.base_urlis used for building login URLs and the expected JWT issuer (iss).authentication.jwks_urldefaults to${base_url}/.well-known/jwks.jsonwhen empty.jku.allowed_host_patternsis a comma/space separated allowlist. Supported patterns:example.com,*.example.com- Not supported: bare
*or mid-string wildcards likeauth*.example.com