DuoAuth

Description:

"DuoAuth" is an adaptive authentication plugin designed to safeguard your Spigot server against impersonation by requiring players to enter a password and 6-digit code (TOTP) combo at the command line (/auth <password> <code>) before they can chat, move, interact, or play on your server.

Passwords are stored as 184-bit bcrypt digests. Since bcrypt is an adaptive password hashing algorithm, the authentication process can be made arbitarily slow by adjusting the cost factor parameter in DuoAuth's configuration file. This allows the plugin to keep up over time with increasing processing power (and remain suitable for less powerful systems by lowering the cost factor).

The 6-digit code is provided from any RFC6238-compliant mobile authentication app (Google Authenticator is recommended). When a player goes through the setup process (i.e. when setting their password), DuoAuth generates and renders a QR code on an in-game map to scan into their mobile authentication app.

Several other configurable items, including minimum password requirements, deauthentication settings, and enforced setup are supported as well.

Installation:

1. Copy DuoAuth.jar into the /plugins directory of your fallback server
2. If you are using BungeeCord, copy DuoAuth.jar into your BungeeCord /plugins directory
3. Assign permissions
4. Start your server
5. Edit your config.yml, lang.yml
6. Restart your server

Permissions:

• duoauth.auth - grants access to the /auth command
• duoauth.bypass - bypass the cooldown time for the /auth command (see config "command.cooldown")
• duoauth.admin - grants access to /auth deauth <player>, /auth reset <player> and /auth check <player>
• duoauth.notify - receive verbose alerts and results when a player uses the /auth command
• duoauth.enforced - forces the player to set up authentication
• duoauth.unlimited - bypass the maximum number of authentication attempts (see config "command.attempts")

None of these permissions are granted by default; they must be explicitly granted to your users and groups.

Configuration:

• bungeecord - true to enable BungeeCord support, false if not (this is only useful for blocking proxy-level commands e.g. /server <server>, /send <player> <server> when players are not authenticated)
• cost-factor - the cost factor of the bcrypt algorithm
  • Min: 12
  • Max: 30
  • Recommended: Set this value in respect to the maximum amount of time you are willing to have your players wait to be authenticated (normally 12-17)
• command
  • cooldown - the cooldown time in seconds for using the /auth command (bypassed by 'duoauth.bypass')
    • Min: 1
    • Recommended: 20
  • attempts - the maximum number of incorrect authentication attempts before players are locked out (bypassed by 'duoauth.unlimited')
    • Recommended: 5+
    • Disable: 0
• password
  • default - the default password to be used when players join with permission 'duoauth.enforced'
  • min-length - the minimum length of a provided password
    • Min: 1
    • Recommended: 8+
  • both-cases - true to enforce at least one uppercase (A-Z) and one lowercase letter (a-z), false if not
    • Recommended: true
  • numbers - true to enforce at least one number (0-9), false if not
    • Recommended: true
  • special-chars - true to enforce at least one special character in the provided 'special-charset', false if not
    • Recommended: true
  • special-charset - the set of characters players must include (at least one) in their passwords
• code
  • issuer - the issuer of the OTP URL
• deauth
  • ip-changes - true to immediately deauthenticate players whenever their IP addresses change, false if not
    • Recommended: true
  • timeout - the time in hours to deauthenticate players after the last successful authentication
    • Min: 1
    • Recommended: 72+
  • timeout-online - true to deauthenticate players even if they are online (can be annoying), false if not
    • Recommended: false
  • timeout-check-heartbeat - the heartbeat in minutes to check if players should be deauthenticated
    • Min: 1
    • Recommended: 10+
• unlock
  • timeout - the time in hours to automatically unlock locked players
    • Recommended: 72+
    • Disable: 0
  • timeout-check-heartbeat - the heartbeat in minutes to check if players should be unlocked
    • Min: 1
    • Recommended: 10+
• database - the method used for storing the digests
  • This is not currently configurable. For now, DuoAuth will only store data in .json files in the /data directory.
• chat - true to allow chat prior to authentication, false if not
• restrict-movement - true to restrict yaw and pitch prior to authentication, false if not

https://github.com/foncused/DuoAuth/blob/master/src/main/resources/config.yml

DuoAuth also generates a second configuration file (lang.yml) to provide customization for messages printed to the chat.
https://github.com/foncused/DuoAuth/blob/master/src/main/resources/lang.yml

Commands:

• /auth (alias /2fa)
  • help - prints /auth command usage
  • generate - generate authentication secret
  • allow <player> - allow a player to bypass authentication ('duoauth.admin' required)
    
  • deauth - deauthenticates the player
  • deauth <player> - deauthenticates a player ('duoauth.admin' required)
  • reset - resets the player's own authentication credentials
  • reset <player> - resets a player's authentication credentials ('duoauth.admin' required)
  • check <player> - check a player's authentication status, logs status to the console ('duoauth.admin' required)
  • <password> <code> - sets up or attempts authentication with the provided password and 6-digit code

The enforced setup ('duoauth.enforced') exists primarily as a way to prevent staff impersonation, including prior to when they would manually set up authentication, by using the default password in the config.yml file. Once they are authenticated and setup with your default password, they will be able to reset themselves and set their own password if they wish (or they can keep the default password - not recommended). The process flow is as follows:

1. Scan the generated QR code or enter the secret key into your mobile authentication app
2. Retrieve the TOTP code from your app
3. /auth <default password> <code>
4. /auth reset
5. /auth generate
6. Repeat steps 1-2, and 3 but with your custom password

Once a player has set up authentication, their credentials will be stored in the plugin's /data directory in <UUID>.json format.

• feb991c8-41e9-4e14-bb11-673ae0ccce8a.json
  
  Code (Text):

  {
    "Password":"$2a$14$hQ7cCEvjnZ.30haqtUKOGOAyGao3MerifrDPHXLTG5wRCmNd22vgW",
    "Secret":"P5PFU7XMFR65SBNO",
    "Authed":false,
    "Attempts":1,
    "IP":"127.0.0.1",
    "Timestamp":"08/17/2019 17:44:26:571"
  }

Ideas:

• Add config option to enable console access to the /auth reset <player> command
• Add subcommand to deauthenticate
• Add lang.yml file to customize plugin messages
• Add support for mobile authentication apps
• Add support for SQLite and MySQL

Support:

To avoid any lag issues or TPS drops, DuoAuth calculates and compares digests in asynchronous tasks. If you run into any server performance problems, or if the plugin is not working as advertised (console errors, bugs, etc.), please do not hesitate to contact me, post in the discussion thread, or open an issue on GitHub. In doing so, it would be beneficial to provide your config.yml, server timings report, and system specs.