How to Install 2FA on Minecraft Servers with GamerSafer
Follow this tutorial to have our secure 2FA service setup for staff two-factor authentication in 5 minutes
With so many challenges that Minecraft Servers face, you can prevent one of them from the start by installing the GamerSafer plugin for staff 2FA in just a few short minutes. Stop staff account theft and spoofing from hackers by locking staff permissions behind secure identity verification and our smartphone app.
This tutorial will not describe the many customizable options that come with GamerSafer, but will instead focus completely on how to get staff 2FA running on your server as easily as possible. This article also assumes you understand how to install and setup a Spigot or Paper powered server and will not cover those steps. Stay tuned to our blog for more integration tutorials in the future that cover other use-cases.
Dependencies:
GamerSafer for Minecraft has several required dependencies that you’ll need to have ready before you begin. Most Minecraft shared server hosts should have a way to open a port or add a MySQL database to your hosting plan.
- The latest GSAuth Plugin from this website
- Java 16 or higher
- Paper or Spigot Server for Java Edition 1.17+
- LuckPerms
- MySQL Database
- An open port for communicating with our service
This list may change in the future as we continue to develop the plugin. Contact us if you have any questions or requests. You will also need the GamerSafer app for iOS or Android devices.
Step 1- Signup for GamerSafer for Minecraft
Before you can start installing and using the GamerSafer for Minecraft plugin, you’ll need to receive an API key which will allow you to receive verification when your staff authenticate with the smartphone app.
To do this, head to the pricing page in the top menu and select the 30 day free trial for the plan you would like to use. For our core service with verified two-factor authentication for a small number of staff, the Iron Tier will work.
Once you have created your server account on this website, which is separate from your GamerSafer app profile, we will contact you within 24 hours to provide the API key and Guild ID for you to use with the plugin, as well as any other downloads or documentation you might need.
Note: When a staff member authenticates, your server will not receive any private data, selfies, or contact information from GamerSafer. We only send a verification success message along with the optional preferences and account data that your player has given us permission to share in the app.
Step 2- Download and Install the GSAuth Plugin (and LuckPerms)
Files in the GSAuth plugin folder on a Paper server
After receiving your API Key and Guild ID from us within 24 hours of signup, you can download the GSAuth plugin from your Server Panel here, and install it just as you would any other Spigot or Paper plugin. Start the server once to generate the required files that will be found in the GSAuth folder in your plugins directory.
You can also install the LuckPerms plugin at this time if you have not already done so. Click here for a tutorial.
Note: You may see several errors or notices in your server’s console when you first install the plugin, but this tutorial should clear those up. With the files now generated in your plugins directory, you can stop the server again and move to the next steps.
Step 3- Input your API Key and Guild ID
An example of the keyinput.txt file where you’ll paste your API Key and Guild ID
Locate and open the keyinput.txt file in the GSAuth folder on your server. You will see the two following lines:
- api-key=YOUR_API_KEY_HERE
- guild-id=YOUR_GUILD_ID_HERE
Copy and paste the API Key and Guild ID that we provided to you in your Server Panel here as shown in the screenshot above. Replace “YOUR_API_KEY_HERE” and “YOUR_GUILD_ID_HERE” with the appropriate keys. Then save and close the file.
Note: After you restart the server, this file will be reset as if you hadn’t added your key and ID yet. That’s normal. The key and ID have been encoded and stored elsewhere as an extra layer of protection. If you are ever in need of resetting your API Key, please contact us and we’ll be happy to send you a new one.
Step 4- Connect your MySQL Database
An example of the config.yml file where you’ll add your MySQL database information
Locate and open the config.yml file in the GSAuth folder on your server. Near the bottom of this file, you will see the following lines:
- connection-string: jdbc:mysql://localhost:3306/databasename
- user: mysqluser
- password: mysqlpass
For “connection-string:”, change “localhost” to the IP address where your MySQL database is located. You can replace “3306” with the port that you are using for the database. Finally, “databasename” should be replaced with the name of an existing database that you previously created where you want to store your GamerSafer data.
The other two lines, “user:” and “password:” are where you will type your MySQL database username and password so that the plugin can connect.
Note: If you are using a shared host, you may need to check their website for information on how to add a MySQL database to your server. After you restart the server, the plugin will attempt to generate a single table in the database you set called “players” where all player UUIDs, guildMemberIDs, and usernames will be stored. The plugin will use this database to see if a member on your server has already joined the GamerSafer guild for your server.
Step 5- Setup the Authentication Webhook Receiver
An example of the config.yml file where you’ll change your authentication settings
In the same config.yml file in the GSAuth folder on your server, you will find the following lines:
- minutes-until-reauth-needed: 1
- url: https://example.com:8001/
The first of those two lines, “minutes-until-reauth-needed:”, allows you to set how long a staff member’s authentication lasts before it expires. By default this is set to 1 minute, meaning that if the staff log out and log back into the server in less than 1 minute, they will not need to reauthenticate with GamerSafer again. You can set this as high as you’d like, but the lower the number, the more secure.
The second line, “url:”, is where you want the plugin to generate a webserver for receiving the authentications from the GamerSafer service. When a player authenticates using our app, we will send a push notification to that webserver. You can change “https:” to “http:” if you are not using TLS, and the “example.com:8001” should be changed to the IP Address and open port you want the service to use.
Our plugin will attempt to generate this webserver for you automatically. If it is not able to do so, you will see an error in the console when you restart the server. Contact us if you need support.
Note: Two additional lines for the certificate and private-key allow you to setup the TLS if you’d prefer “https:” for your webserver. If you use a shared server host, they may have information on their website, or you may need to contact their support, for opening an additional port for you to use on your service. This is very similar to what is done for Dynmap, Plan, and other plugins.
Step 6- Check the GamerSafer “Required” Settings
An example of the config.yml file where you’ll set restrictions for non-authenticated staff members.
Once again, in the same config.yml file as the previous step, look for the “gamersafer-required:” and “not-authenticated:” lines. These are both used in unique ways for various Minecraft use-cases, but we’ll mostly be focused on “gamersafer-required:” for the staff 2FA goal of this tutorial.
What does “gamersafer-required” mean?
“gamersafer-required:” are the settings that will apply only to specific players (or staff members) that you choose. In Step 7 we’ll learn how to select those users who will be required to authenticate, but in this step we’ll define some of the restrictions that you want all gamersafer-required staff members to have.
Change these settings according to your desires, and when a player logs in who is required to authenticate with GamerSafer the options you enable here will be enforced on their account until they authenticate. You can use this to completely stop those required users from chatting, running commands, block breaking, and more with these options. Once they authenticate with GamerSafer, those restrictions are lifted.
What does “permissions-override-group” mean?
The “not-authenticated:” section is used very differently. We’ll cover what this does in more detail in a future blog post about other uses of GamerSafer, but for now you can leave this as “NotAuth” or even make it your default usergroup name in LuckPerms. To put it simply for now, every player that logs in will automatically be added to this “not-authenticated > permissions-override-group” until they authenticate. But it does not force the other “gamersafer-required” restrictions on them.
Step 7- Setup Your GamerSafer LuckPerms Groups
With all of your GamerSafer plugin files edited, you can save the files and restart the server to move into the final setup process of creating the LuckPerms groups that GamerSafer will use. This tutorial assumes you know how to use the “/lp editor” command for LuckPerms. If you don’t, check out their official tutorial here.
Create the “NotAuth” group
LuckPerms Groups and “NotAuth” permissions.
As mentioned before, we’ll go into more detail about how you can use this “NotAuth” group for other use-cases on your server, but for now we will keep it simple. Every player that joins your server, whether they are using GamerSafer or not, will automatically be added to this “NotAuth” group when they login, and removed from it when they logout or authenticate with GamerSafer.
It is required to have this group created even if you aren’t using it at this time. Players will also continue to have their other permissions and groups as normal, but the “NotAuth” group they are added to will override any differences in permissions until they authenticate. If you don’t put anything in this group, it does not affect the players at all.
Create a “StaffRequired” group
This example gsrequired group called “StaffRequired” has only one /mail permission and no others.
The gsrequired groups work very differently from the “NotAuth” group. Instead of adding the players to the group, specific players you choose will have all other groups and permissions removed except for the gsrequired group you want them in. The moment that they authenticate with GamerSafer, they are removed from the gsrequired group and added back to the original groups and permissions you want them to have.
You can use these different gsrequired groups to allow certain players that you want to force to use GamerSafer for 2FA to still have some permissions before they authenticate. In the example screenshot above, staff members would still have the cmi.command.mail permission, but no other permissions would be accessible to them until they authenticate.
For the sake of this tutorial, we will create one group called “StaffRequired”.
Assign staff to be forced into the “StaffRequired” group on login
Any player or group with a “gamersafer.required.{groupname} will automatically be required to authenticate.
Using the example gsrequired group we created before, “StaffRequired”, we can now assign specific users or groups of users to be forced to authenticate by adding the permission “gamersafer.required.staffrequired”.
When a player with that permission logs in, they will have all of their existing groups and permissions removed and they will be forced into the “StaffRequired” group until they authenticate with the app. Once they authenticate, they are removed from the “StaffRequired” group and put back in their normal permissions and groups.
In this example, all members of the “Staff” group will have the “gamersafer.required.staffrequired” permission. This means that when they login they’ll be forced out of the “Staff” group and into the “StaffRequired” group. Once they authenticate with GamerSafer, they will be removed from the “StaffRequired” group and added back to the “Staff” group so that they can get all of their normal staff permissions.
In the event that your server crashes or restarts while a staff member is in one of the gsrequired groups, their other groups are cached and will be restored the next time they log in and authenticate.
Step 8- Celebrate Your New 2FA Setup!
You are now done! With all of these settings in place you can save LuckPerms and restart the server. From this point on your staff will be required to use GamerSafer for verified 2FA before being granted any potentially dangerous permissions.
All that’s left now is for your staff team members (who have the gsrequired permission) to join your GamerSafer Guild by scanning the QR code that appears in-game on your server using our app.
When they scan that QR code to accept the invite, their GamerSafer profile will be linked to your server and every time they log into your server they’ll receive a push notification to their phone asking them to authenticate again.
2FA protects your staff accounts from being hacked on your server, protects your players from downtime, and protects you from headaches caused by these harms.
- Log Into Server
Your server staff log into the server and specific permissions that you choose (like creative mode or WorldEdit) are blocked
2 App Notification
The team member receives a notification in the GamerSafer App and they take a selfie to verify they are logging on
3 Access Granted
The GamerSafer Plugin automatically grants your team member the permissions they need to do their job
Taking action is the best way to impact the Minecraft community
If you liked this blog post, spread the message!
We would love to hear what you’re doing to make the Minecraft community a safer and more inclusive environment.
Tell us about it using the form below.
About the Author
EMAIL:
TWITTER:
Tim has been playing Minecraft and running servers for over 10 years. His experiences in education, development, and community management help the GamerSafer for Minecraft project succeed.
Would you like to see a demo, learn about integration, or contact us about something else?
You can also join our Discord Guild.
Terms of Service – Privacy Policy
© 2019-2023, GAMERSAFER, Inc. All rights reserved. GAMERSAFER trademarks are registered in the US.