MCAuthenticator is a Bukkit API based plugin designed to allow for 2 Factor Authentication (otherwise known as TOTP, or the Time-Based One-Time Password Algorithm (RFC6238)) for all players on a server to optionally use, with configurable enforcement for certain players through permission nodes. This is designed to allow for more secure minecraft server environments, especially when account cracking and hacking are so prevalent. This plugin reduces the risk of a compromised staff account greatly, making it much harder to compromise a staff account and compromise a server in general.
To install MCAuthenticator, you simply put the MCAuthenticator.jar within
the plugins/ folder of your Bukkit/Spigot/BungeeCord server. Once you start the
server, the plugin will generate a configuration as described below.
MCAuthenticator is tested with Spigot 1.8.8, on Java 8. However, MCAuthenticator is compatible with Java 7, and there is no reason it shouldn't work with Bukkit 1.6.x or 1.7.x servers. We will officially support 1.6.x spigot and up.
If you find issues on any server versions 1.6.x and up, please report them in issues.
MCAuthenticator uses 1 root command, /auth (with aliases /2fa, /authenticator, and /mcauthenticator) with a set of sub commands:
- /auth enable [player] - Enables 2FA on an account, or your own account if a player isn't specified.
- /auth disable [player] - Disables 2FA on an account, or your own account if a player isn't specified.
- /auth reset [player] - Keeps 2FA enabled, but resets the 2FA on your account or another player's if player is specified.
- /auth reload - Reloads the configuration, then re-authenticates all players based on configured authentication rules.
MCAuthenticator uses the root permission mcauthenticator, with a set of sub
permissions to control the behaviour of various aspects of the plugin.
Each permission has one of two defaults: op and console only. If a permission is defaulting to console only, even if a player has op, they will not be able to perform the command unless they explicitly have the listed permission.
mcauthenticator.use(default: op) - Allows for the root use of the /auth command. In order to do anything with the /auth command, the player must have this permission.mcauthenticator.enable(default: op) - Allows for the user to do /auth enable on themselves. This does not control whether the player is allowed to have 2FA enabled on their account; if console or a player withmcauthenticator.enable.otherenables 2FA on their account, the plugin will let them.mcauthenticator.disable(default: op) - Allows for the user to do /auth disable on themselves.mcauthenticator.enable.other(default: console only) - Allows for the user to perform /auth enable , enabling authentication for another player. The other player does not need to havemcauthenticator.enablein order to have 2FA enabled on their account.mcauthenticator.disable.other(default: console only) - Allows for the user to perform /auth disable , disabling another player's authentication.mcauthenticator.reset(default: op) - Allows for a player to reset their own account's authentication.mcauthenticator.reset.other(default: console only) - Allows for the user to reset other user's authentications.mcauthenticator.reload(default: console only) - Allows for the user to reload the configuration
mcauthenticator.lock(default: op) - Does one of 2 things:- Forces the user to always 2FA enabled, not allowing them to disable or reset their own authentication
- Does not allow anyone but console to reset or disable their authentication.
Even if the user has any of the
.otherpermission nodes, the plugin will not allow them to perform any changes to authentication. This should be given to any staff members, as it will prevent any other compromised account from then chainly compromising other staff (or important persons) accounts.
The configuration of the plugin can be default out of the box, but it is highly suggested that at least some of the configuration defaults be customized to your server.
All of the configuration is located in plugins/MCAuthenticator/config.yml. Each
of the configuration options listed below are all located within this yml.
Since 1.1.0, MCAuthentication has supported multiple types of
authentication mechanisms:
- 2fa
- Yubikey
Each of these can be turned on and off within the config file under
authenticators. When setting up 2FA, the user may use any of the
configured authentication mechanisms. The plugin will auto-detect which
mechanism they use, and authenticate them off of only that method in the
future.
In order to offer authentication through Yubikey, you must have a
clientId as well as a clientSecret. Both of these are offered at
https://upgrade.yubico.com/getapikey/. If you do not add these
api credentials, Yubikey authentication will not function correctly.
These should be entered under yubikey within the configuration.
The serverIp field specifies what will be displayed to the user within their
2FA app.
For example, with a username Ichbinjoe and serverIp set to ibj.io, a sample
GAuth entry will look like the following:
By default, MCAuthenticator does not force a player to re-authenticate if they rejoin
from the last IP they were authenticated from. This can be disabled by setting
forceSameIPAuthentication to true. When set to true, the plugin force the user to
re-authenticate through 2FA each and every time they log into the server.
Under the messages section of the configuration, MCAuthenticator allows you to
customize all publicly displayed messages, in order to modify color schemes and
the prefix to better fit your server's color scheme/language requirements. All
staff commands are hardcoded, simply because there is much less of a reason to
customize these messages.
Each entry supports &<opcode> based colorcodes, as well as the \n character
for splitting up messages onto multiple lines. Where contextually logical, a
%player% replacement has been added to customize each message based on occurrence.
MCAuthenticator supports 1 of 3 different data sources:
- Single File - Stores all player data in one file
- Directory - Stores each player in their own file within a directory
- MySQL - Stores all player data within a table in a MySQL/MariaDB table.
To enable the single file data source, dataBacking.type should be set to single.
The file to which the single file data source saves to is configured by setting
dataBacking.file. This file is then by default present in plugins/MCAuthenticator
To enable the directory data source, dataBacking.type should be set to directory.
The directory to which all of the player data is saved is configured by the
dataBacking.directory field. Within this directory, a file for each player,
structured <uuid>.json stores a single JSON object with the authentication
details.
To enable the MySQL data source, dataBacking.type should be set to mysql.
The database connection details should then be set in dataBacking.mysql.
The default connection url is jdbc:mysql://localhost:3000/db, with the format
jdbc:mysql://<ip>:<port>/<databaseName>. username and password should also
be set to a username and password that is able to access the database.
To build MCAuthenticator, run mvn package in a command terminal, and the
result of the build will save the jar to target/MCAuthenticator-<version>.jar.
BungeeCord support will only require one authentication per player join, not every
time the player switches servers, does not require same IP to be true, and will deny
BungeeCord commands until the player is authenticated. To enable BungeeCord support,
enable under the bungee should be set to true, and channel should be set to
the same channel as the BungeeCord plugin's pluginChannel is set to. BungeeCord
mode requires that the plugin also be installed on the BungeeCord instance(s).
We love contributions! Feel free to fork this project and PR any changes/ enhancements! Of note, we use the MIT License, which is listed here.
We request that issues/ suggestions be submitted on the Github issue manager. This allows us to be more vigilant of issues, and allow more flexibility in managing the project.