# DownAuth<\/p>\n
Fallback authentication for Velocity proxy with strong, configurable security controls when Mojang auth is unavailable.<\/p>\n
## Overview
\n– **Purpose**: Allow trusted players to join using their cached session if Mojang authentication is down.
\n– **How**: Switches to offline-mode for the affected connection, validates against a cached session, and applies layered security checks to reduce spoofing risk.<\/p>\n
## Key Features
\n– **Fallback authentication**
\n – Uses cached session data: UUID, username, last known IP, timestamps, GameProfile properties (skin\/cape).
\n – Automatically activates when Mojang auth appears down; reverts when back up.<\/p>\n
– **Service health monitoring**
\n – Periodic checks drive fallback enable\/disable logic.
\n – Tunable health check interval and failure threshold.<\/p>\n
– **Audit logging (optional)**
\n – Writes security events (fallback used, geo\/ASN change, PIN prompts) to `audit.log`.<\/p>\n
– **IP validation with IPv6 support**
\n – Strict IP match by default.
\n – Optional network range matching with configurable CIDR for IPv4 and IPv6.<\/p>\n
– **Geo\/ASN checks**
\n – Looks up the country code and ASN of the connecting IP.
\n – Alerts staff on large changes; can optionally deny fallback until a normal online-mode login occurs again.
\n – ASN blocklist to deny known hosting\/VPN networks during fallback.
\n – Provider URL, timeout, and response cache TTL are configurable.<\/p>\n
– **Rate limiting**
\n – Per-IP and per-UUID attempt throttling.
\n – Extended throttling per-subnet and per-ASN to slow broad spoof attempts.<\/p>\n
– **PIN verification during outages (optional)** - **Admin alerts** - **Storage** ## Commands ## Permissions ## Configuration (excerpt) security: monitoring: messages: ## Security messages and when they appear ## How it works (high level) ## Geo provider ## Notes Fallback for Velocity in the event of Mojang Outages<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"_minecraft_slug":"downauth","_minecraft_project_id":"fzkaAoGw","_minecraft_author":"Bobcat","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":28,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"downauth.zip","_minecraft_size_bytes":55762,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:12:07.624773Z","_minecraft_date_created":"2025-10-30T06:29:24.233684Z","_minecraft_date_modified":"2025-10-29T18:44:59.536223Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/downauth","_minecraft_icon_attachment_id":0,"_minecraft_imported_at":"2026-06-03T05:08:53+00:00","_minecraft_import_hash":"32c33c4e7bbef4f8ef77bbef548b1b5e","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[89,123,92,985],"mod_loader":[986],"minecraft_version":[40,801,79,780,781,782,783,784,80,785,786,82,796,797,798,799,800,778,779,790,791,792,793,794,802,803,804],"class_list":["post-58558","mod","type-mod","status-publish","hentry","mod_category-game-mechanics","mod_category-technology","mod_category-utility","mod_category-velocity","mod_loader-velocity","minecraft_version-1-21-10","minecraft_version-1-21-10-rc1","minecraft_version-1-21-6","minecraft_version-1-21-6-pre1","minecraft_version-1-21-6-pre2","minecraft_version-1-21-6-pre3","minecraft_version-1-21-6-pre4","minecraft_version-1-21-6-rc1","minecraft_version-1-21-7","minecraft_version-1-21-7-rc1","minecraft_version-1-21-7-rc2","minecraft_version-1-21-9","minecraft_version-1-21-9-pre1","minecraft_version-1-21-9-pre2","minecraft_version-1-21-9-pre3","minecraft_version-1-21-9-pre4","minecraft_version-1-21-9-rc1","minecraft_version-25w20a","minecraft_version-25w21a","minecraft_version-25w34a","minecraft_version-25w34b","minecraft_version-25w35a","minecraft_version-25w36a","minecraft_version-25w36b","minecraft_version-25w41a","minecraft_version-25w42a","minecraft_version-25w43a"],"yoast_head":"\n
\n – Require players to set a PIN during normal operation; when fallback is used, they must verify with `\/pin ` within a timeout.
\n - Players are reminded on join to set a PIN if the policy requires it and they don\u2019t have one yet.
\n - PINs are stored hashed (SHA-256) in the cached session.<\/p>\n
\n - Notify players with `downauth.alert` when fallback is used or when a geo\/ASN change is detected.<\/p>\n
\n - JSON on-disk session storage with optional cleanup on startup.<\/p>\n
\n- `\/setpin `
\n - Sets a personal fallback PIN (minimum length configurable).
\n- `\/pin `
\n - If a verification is pending (during fallback), verifies the code.
\n - If no verification is pending, sets the PIN as a convenience.
\n- `\/resetpin`
\n - Clears your PIN only when Mojang auth is healthy (online-mode path).<\/p>\n
\n- **downauth.alert**
\n - Receive staff alerts about fallback usage and geo\/ASN changes.
\n- Commands do not enforce additional permissions by default. Use your proxy\u2019s permission system if you want to restrict them.<\/p>\n
\n```yaml
\nsession-cache:
\n max-session-age: 72
\n storage-type: \"JSON\"
\n strict-ip-check: true
\n allow-ip-range-match: true
\n ipv4-range-prefix: 24
\n ipv6-range-prefix: 64
\n cleanup-on-startup: true<\/p>\n
\n min-login-history: 3
\n max-failed-attempts: 10
\n failure-ban-duration: 30
\n require-recent-activity: true
\n recent-activity-days: 30
\n alert-on-fallback: true
\n enable-geo-checks: true
\n alert-on-geo-change: true
\n deny-on-geo-change: false
\n require-pin-on-fallback: false
\n pin-timeout-seconds: 60
\n pin-min-length: 6
\n max-failed-attempts-per-subnet: 30
\n max-failed-attempts-per-asn: 100
\n blocked-asns: []
\n require-mojang-auth: [] # UUIDs that must always authenticate online<\/p>\n
\n health-check-interval: 30
\n failure-threshold: 3
\n enable-statistics: true
\n enable-metrics: true
\n enable-audit-log: true
\n geo-lookup-timeout: 2000
\n geo-provider-url: \"https:\/\/ipwho.is\/{ip}?fields=ip,country_code,connection\"
\n geo-cache-ttl: 300<\/p>\n
\n fallback-auth-active: \"&eAuthentication servers are down. Using cached session.\"
\n fallback-auth-failed: \"&cCannot authenticate: No cached session found.\"
\n session-expired: \"&cYour session has expired. Please try again when auth servers are online.\"
\n mojang-down-notice: \"&7Mojang authentication servers appear to be down.\"
\n pin-prompt: \"&ePlease verify your identity: use &6\/pin &e within &6%timeout%s\"
\n pin-success: \"&aVerification successful.\"
\n pin-failure: \"&cIncorrect PIN.\"
\n pin-required-notice: \"&ePins are required during auth outages. Set your PIN with &6\/setpin &e.\"
\n geo-denied: \"&cConnection denied due to location or network change. Please try again later.\"
\n```<\/p>\n
\n- **fallback-auth-active**: Sent to staff with `downauth.alert` when fallback is used.
\n- **fallback-auth-failed**: Sent to the player if no cached session exists while in fallback.
\n- **session-expired**: Sent to the player if their cached session is too old or invalid.
\n- **mojang-down-notice**: General heads-up when services seem to be down (used by the plugin in appropriate places).
\n- **pin-prompt**: Direct message to a player who must verify their PIN during fallback; they must run `\/pin ` before the timeout.
\n- **pin-success \/ pin-failure**: Results of PIN verification.
\n- **pin-required-notice**: Reminds players (on join) to set a PIN when policy requires pins during outages and they don\u2019t have one yet.
\n- **geo-denied**: Disconnect reason if policy denies fallback on geo\/ASN change while services are down.<\/p>\n
\n1. **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.
\n2. **GameProfileRequest**: Supplies a profile built from the cached session (UUID, name, properties).
\n3. **PostLogin**: Updates the session, re-checks geo\/ASN, alerts staff if needed, and optionally enforces PIN verification.<\/p>\n
\n- Default provider: `ipwho.is` (no key required). You can change the provider URL and tune timeouts and TTL in `monitoring`.<\/p>\n
\n- This plugin is designed for Velocity proxy environments. Place the jar into the proxy\u2019s `plugins\/` folder. Adjust `config.yml` as needed, then restart the proxy.
\n- If you enable PINs, ensure players set their PINs while authentication is healthy to avoid disruption when outages occur.<\/p>\n","protected":false},"excerpt":{"rendered":"