DownAuth
当 Mojang 认证服务不可用时,为 Velocity 代理提供后备身份验证功能,具备强大且可配置的安全控制措施。
概述
- 用途:在 Mojang 认证服务宕机时,允许受信任的玩家使用缓存会话加入服务器。
- 原理:将受影响连接的认证模式切换为离线模式,通过验证缓存会话来确认身份,并应用多层安全检查以降低伪造风险。
主要功能
-
后备身份验证
- 使用缓存的会话数据:UUID、用户名、最后已知 IP 地址、时间戳、GameProfile 属性(皮肤/披风)。
- 当检测到 Mojang 认证服务宕机时自动激活;服务恢复后自动回退。
-
服务健康监控
- 定期执行检查以驱动后备功能的启用/禁用逻辑。
- 可调整健康检查间隔和失败阈值。
-
审计日志(可选)
- 将安全事件(如使用后备验证、地理位置/ASN 变更、PIN 码提示)写入
audit.log。
-
IP 验证,支持 IPv6
- 默认严格匹配 IP 地址。
- 可选网络范围匹配,支持针对 IPv4 和 IPv6 的可配置 CIDR 前缀。
-
地理位置/ASN 检查
- 查询连接 IP 的国家代码和 ASN(自治系统号)。
- 对大幅变更发出警报;可选择在恢复正常在线模式登录之前拒绝后备验证。
- 支持 ASN 黑名单,可在后备验证期间拒绝已知的托管/VPN 网络。
- 提供商 URL、超时时间和响应缓存 TTL 均可配置。
-
速率限制
- 按 IP 和 UUID 进行尝试频率限制。
- 按子网和 ASN 进行扩展限流,以减缓大规模伪造尝试。
-
宕机期间的 PIN 码验证(可选)
- 要求玩家在正常运行期间设置 PIN 码;当使用后备验证时,必须在超时前通过
/pin <code> 进行验证。
- 如果策略要求且玩家尚未设置 PIN 码,会在加入时提醒其设置。
- PIN 码以哈希形式(SHA-256)存储在缓存会话中。
-
管理员警报
- 当使用后备验证或检测到地理位置/ASN 变更时,向拥有
downauth.alert 权限的玩家发送通知。
-
存储
- 使用 JSON 文件在磁盘上存储会话数据,支持启动时清理。
命令
/setpin <code>
/pin <code>
- 如果有待验证的请求(处于后备状态),则验证该代码。
- 如果没有待验证的请求,则作为便捷操作设置 PIN 码。
/resetpin
- 仅在 Mojang 认证服务正常(在线模式路径)时清除你的 PIN 码。
权限
- downauth.alert
- 接收关于后备使用和地理位置/ASN 变更的管理员警报。
- 命令默认不强制执行额外权限。如需限制,请使用你代理的权限系统。
配置(节选)
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: [] # 必须始终进行在线认证的 UUID 列表
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: "&e认证服务器已宕机。正在使用缓存会话。"
fallback-auth-failed: "&c无法认证:未找到缓存会话。"
session-expired: "&c你的会话已过期。请在认证服务器上线后重试。"
mojang-down-notice: "&7Mojang 认证服务器似乎已宕机。"
pin-prompt: "&e请验证你的身份:在 &6%timeout%s&6 内使用 &6/pin <code>&e。"
pin-success: "&a验证成功。"
pin-failure: "&cPIN 码不正确。"
pin-required-notice: "&e认证宕机期间需要 PIN 码。请使用 &6/setpin <code>&e 设置你的 PIN 码。"
geo-denied: "&c因位置或网络变更导致连接被拒。请稍后重试。"
安全消息及其触发时机
- fallback-auth-active:当使用后备验证时,发送给拥有
downauth.alert 权限的管理员。
- fallback-auth-failed:如果在后备状态下没有缓存会话,则发送给玩家。
- session-expired:如果玩家的缓存会话过期或无效,则发送给玩家。
- mojang-down-notice:当服务似乎宕机时的一般提示(插件会在适当位置使用此消息)。
- pin-prompt:发送给必须在后备验证期间验证 PIN 码的玩家;他们必须在超时前运行
/pin <code>。
- pin-success / pin-failure:PIN 码验证的结果。
- pin-required-notice:当策略要求在宕机期间使用 PIN 码且玩家尚未设置时,在加入时提醒玩家设置 PIN 码。
- geo-denied:如果策略在服务宕机期间因地理位置/ASN 变更而拒绝后备验证,则作为断开连接的原因。
工作原理(高层级)
- PreLogin:如果 Mojang 认证服务似乎宕机,连接将切换为离线模式,并根据缓存会话结合 IP/速率/地理位置/ASN 检查进行验证。
- GameProfileRequest:提供基于缓存会话构建的资料文件(UUID、名称、属性)。
- PostLogin:更新会话,重新检查地理位置/ASN,必要时通知管理员,并可选择强制 PIN 码验证。
地理位置提供商
- 默认提供商:
ipwho.is(无需密钥)。你可以在 monitoring 部分更改提供商 URL 并调整超时时间和 TTL。
注意事项
- 本插件专为 Velocity 代理环境设计。将 jar 文件放入代理的
plugins/ 文件夹中。根据需要调整 config.yml,然后重启代理。
- 如果启用了 PIN(个人识别码),请确保玩家在身份验证正常时设置其 PIN,以避免在出现故障时造成中断。
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)
- 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.
- GameProfileRequest: Supplies a profile built from the cached session (UUID, name, properties).
- 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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧