DownAuth

Fallback authentication for Velocity proxy with strong, configurable security controls when Mojang auth is unavailable.

Overview

• Purpose: Allow trusted players to join using their cached session if Mojang authentication is down.
• How: Switches to offline-mode for the affected connection, validates against a cached session, and applies layered security checks to reduce spoofing risk.

Key Features

• Fallback authentication

  • Uses cached session data: UUID, username, last known IP, timestamps, GameProfile properties (skin/cape).
  • Automatically activates when Mojang auth appears down; reverts when back up.

• Service health monitoring

  • Periodic checks drive fallback enable/disable logic.
  • Tunable health check interval and failure threshold.

• Audit logging (optional)

  • Writes security events (fallback used, geo/ASN change, PIN prompts) to audit.log.

• IP validation with IPv6 support

  • Strict IP match by default.
  • Optional network range matching with configurable CIDR for IPv4 and IPv6.

• Geo/ASN checks

  • Looks up the country code and ASN of the connecting IP.
  • Alerts staff on large changes; can optionally deny fallback until a normal online-mode login occurs again.
  • ASN blocklist to deny known hosting/VPN networks during fallback.
  • Provider URL, timeout, and response cache TTL are configurable.

• Rate limiting

  • Per-IP and per-UUID attempt throttling.
  • Extended throttling per-subnet and per-ASN to slow broad spoof attempts.

• PIN verification during outages (optional)

  • Require players to set a PIN during normal operation; when fallback is used, they must verify with /pin <code> within a timeout.
  • Players are reminded on join to set a PIN if the policy requires it and they don’t have one yet.
  • PINs are stored hashed (SHA-256) in the cached session.

• Admin alerts

  • Notify players with downauth.alert when fallback is used or when a geo/ASN change is detected.

• Storage

  • JSON on-disk session storage with optional cleanup on startup.

Commands

• /setpin <code>
  • Sets a personal fallback PIN (minimum length configurable).
• /pin <code>
  • If a verification is pending (during fallback), verifies the code.
  • If no verification is pending, sets the PIN as a convenience.
• /resetpin
  • Clears your PIN only when Mojang auth is healthy (online-mode path).

Permissions

• downauth.alert
  • Receive staff alerts about fallback usage and geo/ASN changes.
• Commands do not enforce additional permissions by default. Use your proxy’s permission system if you want to restrict them.

Configuration (excerpt)

session-cache:
  max-session-age: 72
  storage-type: "JSON"
  strict-ip-check: true
  allow-ip-range-match: true
  ipv4-range-prefix: 24
  ipv6-range-prefix: 64
  cleanup-on-startup: true

security:
  min-login-history: 3
  max-failed-attempts: 10
  failure-ban-duration: 30
  require-recent-activity: true
  recent-activity-days: 30
  alert-on-fallback: true
  enable-geo-checks: true
  alert-on-geo-change: true
  deny-on-geo-change: false
  require-pin-on-fallback: false
  pin-timeout-seconds: 60
  pin-min-length: 6
  max-failed-attempts-per-subnet: 30
  max-failed-attempts-per-asn: 100
  blocked-asns: []
  require-mojang-auth: []  # UUIDs that must always authenticate online

monitoring:
  health-check-interval: 30
  failure-threshold: 3
  enable-statistics: true
  enable-metrics: true
  enable-audit-log: true
  geo-lookup-timeout: 2000
  geo-provider-url: "https://ipwho.is/{ip}?fields=ip,country_code,connection"
  geo-cache-ttl: 300

messages:
  fallback-auth-active: "&eAuthentication servers are down. Using cached session."
  fallback-auth-failed: "&cCannot authenticate: No cached session found."
  session-expired: "&cYour session has expired. Please try again when auth servers are online."
  mojang-down-notice: "&7Mojang authentication servers appear to be down."
  pin-prompt: "&ePlease verify your identity: use &6/pin <code>&e within &6%timeout%s"
  pin-success: "&aVerification successful."
  pin-failure: "&cIncorrect PIN."
  pin-required-notice: "&ePins are required during auth outages. Set your PIN with &6/setpin <code>&e."
  geo-denied: "&cConnection denied due to location or network change. Please try again later."

Security messages and when they appear

• fallback-auth-active: Sent to staff with downauth.alert when fallback is used.
• fallback-auth-failed: Sent to the player if no cached session exists while in fallback.
• session-expired: Sent to the player if their cached session is too old or invalid.
• mojang-down-notice: General heads-up when services seem to be down (used by the plugin in appropriate places).
• pin-prompt: Direct message to a player who must verify their PIN during fallback; they must run /pin <code> before the timeout.
• pin-success / pin-failure: Results of PIN verification.
• pin-required-notice: Reminds players (on join) to set a PIN when policy requires pins during outages and they don’t have one yet.
• geo-denied: Disconnect reason if policy denies fallback on geo/ASN change while services are down.

How it works (high level)

1. PreLogin: If Mojang auth appears down, the connection is switched to offline-mode and validated against the cached session with IP/rate/geo/ASN checks.
2. GameProfileRequest: Supplies a profile built from the cached session (UUID, name, properties).
3. PostLogin: Updates the session, re-checks geo/ASN, alerts staff if needed, and optionally enforces PIN verification.

Geo provider

• Default provider: ipwho.is (no key required). You can change the provider URL and tune timeouts and TTL in monitoring.

Notes

• This plugin is designed for Velocity proxy environments. Place the jar into the proxy’s plugins/ folder. Adjust config.yml as needed, then restart the proxy.
• If you enable PINs, ensure players set their PINs while authentication is healthy to avoid disruption when outages occur.