Configuration

Storage

The "storage" section is how 2FA+ stores long-term data. Let's break the section down.

storage:

The "method" is how the data will be stored. The current storage methods are outlined here.

  method: 'sqlite'

The "data" section gives a way to connect to a remote database and defines how the data is organized. You may specify a remote database address, username, password, whether or not to use SSL, and in the case of MongoDB the connection prefix and uri.

You may also specify the database name (which in the case of remote databases will need to be created first) and table prefix (in case you want to use a "global" database.)

  data:
    address: '127.0.0.1:3306'
    database: '2faplus'
    prefix: '2faplus_'
    username: ''
    password: ''
    ssl: false

    mongodb:
      collection-prefix: ''
      connection-uri: ''

The "settings" section allows setting the number of connections in the pool and various connection timeout, lifetime, and encoding settings.

The "max-pool-size" is the maximum number of connections the plugin will make to a given database. The "min-idle" is the minimum number of connections the plugin will keepalive after non-use. It's generally good practice to keep these two numbers the same.

The "max-lifetime" is how long a connection will live for before being re-created, and "timeout" is how long the plugin will wait before giving up on a new connection. Generally, you won't need to touch these, but if your database setup is different then you may want to have a second look.

Similarly, the "properties" section defines what encoding to use and whether or not to use Unicode. Generally, you won't need to change these, but they're here if you do.

  settings:
    max-pool-size: 2
    min-idle: 2
    max-lifetime: 1800000 # 30 minutes
    timeout: 5000 # 5 seconds

    properties:
      unicode: true
      encoding: 'utf8'

Redis/RabbitMQ

The "Redis" and "RabbitMQ" sections allow you to connect to an existing Redis or RabbitMQ installation so they may be used for cache storage or to push instant updates across servers.

If you use Redis, set "enabled" here to true and fill in the address (+port, if needed) and password (if needed) for the Redis installation.

redis:
  enabled: false
  address: '127.0.0.1:6379'
  password: ''

If you use RabbitMQ, set "enabled" here to true and fill in the address (+port, if needed) and username/password for the Rabbit installation.

rabbitmq:
  enabled: false
  address: '127.0.0.1:5672'
  username: 'guest'
  password: 'guest'

Services

2FA+ uses multiple services to give you more options for setting 2-factor auth up for your server.

Authy

Authy is the easiest to set up and most convenient for your staff and players. It's a multi-platform project and is extremely easy to use. The downside is it's a little bit harder to add a new user to the plugin. (requires knowing the player's phone number)

The Authy services requires creating an API key and then adding that key into the "authy" section of the config.

authy:
  key: ''

OTP

OTP (TOTP and HOTP) is slightly more difficult to set up and will be only very slightly less convenient for staff and players. The upside is that's it's very easy to register a new player with the system, and once set up on the player's end it's easy to use as well.

OTP is standard and supported by all major 2FA apps such as Google Authenticator, Duo, the Authy app, and more.

OTP comes enabled by default, but you may wish to change the "issuer" to your server/network's name. You may also wish to change the "digits" to a reasonable number of your choice.

otp:
  digits: 6
  issuer: '2FAPlus'

"digits" is how many numbers will be generated with OTP (6 is usually a good default). For example, 6 will generate a code like "123 456", 7 will generate a code like "12 345 67", and so on.

The "issuer" is the name that will appear on OTP apps such as the ones listed above.

2FA

the "2fa" section is the main body of the plugin's work. It specifies exactly how the plugin will protect your server. 2FA+ will protect player logins, commands, and world interactions by default.

Login

By default, 2FA+ protects your server from rogue logins by players and staff who should be authenticated. This is intended as a "first-time setup" so you can get the plugin properly configured before your server is attacked.

When a player or staff logs in and successfully authenticates, their IP is logged and stored for a certain amount of time. This allows the plugin to automatically authenticate a player who logs in repeatedly without them needing to re-authenticate using their device every time they do so. If the player's IP changes (vacation, dynamic updates, etc) they will need to re-authenticate once again. This prevents attackers from "riding" on a pre-authenticated player.

The system keeps track of all IPs used to authenticate, so if a player authenticates from their home and then goes on vacation for a few days, they will still be authenticated at their home when they return.

2fa:
  ip-lifetime: '30days'
  force-auth: true
  no-auth-kick-message: '&cPlease set up 2FA with your admin team before logging in!'
  max-attempts: 3
  too-many-attempts-kick-message: '&cYou have attempted 2FA too many times!'
  too-many-attempts-command: ''

The "ip-lifetime" is how long to store the player's IP for automatic authentication. The default is 30 days, which means a player (or staff) will only need to authenticate once a month as long as they don't change locations.

"force-auth" can go one of two ways. If it's set to "true" (default) the plugin will force ALL players that log into the server to authenticate. If a player doesn't have 2FA enabled, they will be kicked with the defined message in the config. If it's set to "false", then the plugin will only authenticate players who have 2FA set up and enabled. It will allow all players to log in, and any that have 2FA set up will be requested to enter their 2FA code.

"max-attempts" is the maximum number of 2FA attempts a player can do before the system kicks them from the server. This prevents brute-forcing of 2FA codes.

The "too-many-attempts-X" configs are for telling 2FA+ what to do after too many authentication attempts. By default, the plugin will simply kick the player. You may wish to change this behavior, however.

When the "too-many-attempts-kick-message" is set the plugin will kick the player with the defined message.

When the "too-many-attempts-command" is set the plugin will run the command specified as the console user. You may use "%player%" in place of the player's real name, and "%uuid%" in place of the player's UUID when creating the command to be run.

If both are set, the command will always run before the player is kicked.

If you set "too-many-attempts-kick-message" to an empty value 2FA+ won't kick players. Similarly, if you set the "too-many-attempts-command" to an empty string the system won't run any command.

Commands

2FA+ also protects certain commands from being run without first authenticating. When a player runs a protected command (defined in the config) the system will ask them to authenticate. If the player runs another protected command within the defined "verification lifetime" the plugin will not ask for authentication again and will reset their verification countdown/timer. After the verification lifetime expires, the player will be asked to re-authenticate when running a protected command.

This system prevents an entire class of attacks that were previously exploited multiple times through "command books" and similar attacks.

2fa:
  verification-lifetime: '3minutes'
  command-list:
  - 'op'
  - 'deop'
  - 'lp'
  - 'luckperms'
  - 'perms'
  - 'permissions'
  - 'perm'
  - 'pex'
  - 'gm'
  - 'groupmanager'
  - '2faplus'
  - 'tfaplus'
  - '2fa'
  - 'tfa'

"verification-lifetime" is how long the player will stay verified for once a player runs a protected command and successfully authenticated themselves. This will allow the player to run another protected command within that time limit without needing to authenticate again. The timer will reset every time a protected command is run.

"command-list" is the commands that are protected from 2FA. The command are protected in both normal form and ":" form. For example, if you add "back" to the list, it will protect both "/back" and "/essentials:back"

Interactions

Finally, 2FA+ prevents players from interacting with or changing the world around them without first authenticating. This will prevent high-level staff or players with trust from permanently damaging builds, stealing from locked chests, successfully posing as the real player in chat, and more.

In order to do the things configured under the "freeze" section in the config, the player or staff will first have to authenticate using the plugin.

  freeze:
    command: true
    chat: true
    interact: true
    attack: true
    inventory: true
    drops: true
    blocks: true
    move: true

"command" will stop the player from running ANY command until authenticated.

"chat" will stop the player from talking in chat without first authenticating.

"interact" will prevent the player from interacting with things (levers, doors, camels, etc) until authenticated.

"attack" will prevent the player form attacking or killing anything until authenticated.

"inventory" will prevent the player from messing with anything in their (or others) inventories without first being authenticated.

"drops" prevents the player from dropping items on the ground without being authenticated.

"blocks" prevents the player from breaking or placing blocks until they authenticate themselves.

"move" will prevent the player from moving (but NOT falling!) until they are authenticated.

Ignore list

The "ignore" list is a list of IPs or UUIDs that bypass 2FA. This will skip checking for any player that connects from any IP defined here, or any player with a UUID defined here.

WARNING

Adding to this list will SIGNIFICANTLY decrease security, since anyone connecting from these IPs (or with these UUIDs) will completely bypass the system. Seriously, think long and hard before using this list.

By using this plugin, you are trading some convenience for security. By trading some of that back all you've done is gained the worst of both worlds.

  ignore:
  - '127.0.0.1'
  - 'localhost'
  - '::1'
# - '069a79f4-44e9-4726-a5be-fca90e38aaf5' #Notch

General

These are some general/misc options that you may or may not want to play with.

Enabling "debug" will tell the plugin to print a LOT more information about its actions to the console. This is very useful when debugging the plugin or trying to figure out why you're getting a particular result from a particular player.

debug: false

This section defines whether or not the plugin will send usage and error stats to the author. Usage stats are provided to bstats and error reports are sent to GameAnalytics.

stats:
  usage: true
  errors: true

This section defines whether or not the plugin checks for updates, and whether or not players with the "2faplus.admin" permission node are notified of updates on login.

update:
  check: true
  notify: true