SSL Certificate (HTTPS) Set Up
This tutorial attempts to guide you through setting up HTTPS on Plan.
Benefits:
- User login is enabled & data is encrypted during transmit
- Plugin Version history data becomes visible
These icons are used to aid during installation
💭 Question about possible issues (Someone has had these before)
📢 Important note about the settings being changed
🚧 Additional steps for some users
💡 Extra stuff
Before getting started with the tutorial, here are some alternatives to this tutorial.
- If you're already using a reverse-proxy with https, you can set up Proxy-settings to transmit in http internally.
- If you're not able to obtain a certificate, you can use self-signed certificate (Will show a warning when the page is opened)
- If you can't set up https in any way but still want to secure your website, you can use the built in IP whitelist, which supports listing IPs, CIDR, or Dynamic DNS addresses.
- A domain you can control (eg
example.com). - Plan installed on a server
Here are the goals the tutorial aims to guide you through.
At the end of this tutorial you will have
- .. obtained a free certificate from Let's Encrypt with Certbot
- .. (or obtained a certificate from elsewhere)
- .. turned the certificate files into a PKCS12 file
.p12with OpenSSL - .. (or installed the certificate on your reverse-proxy)
- .. Secured Plan with HTTPS & Login
After installation it is also possible to
- .. register users for Plan
- .. modify what users can see on the website
Let's Encrypt is a free certificate authority that allows you to get a certificate for you domain easily. They maintain Certbot which allows them to verify that you own a domain, and generate the certificate files for you.
You will be able to obtain .pem certificate files with Certbot. Let's install it.
💡 Advanced Users
Certbot documentation can be found from https://eff-certbot.readthedocs.io/en/latest/
- Open Certbot tutorial
- Select 'Other' and Operating System of your server.
- Scroll down to 'default' / 'wildcard *' and select 'wildcard *'.
- Follow installation instructions for Certbot.
- Continue to step 2 after you have a command prompt / terminal open with working certbot command: (Running the command needs sudo on Linux or CMD/Powershell open as Adminstrator)
certbot --help
- Open Certbot tutorial
- Select 'Other' and Operating System of your computer.
- Scroll down to 'default' / 'wildcard *' and select 'wildcard *'.
- Follow installation instructions for Certbot.
- Continue to step 2 after you have a command prompt / terminal open with working certbot command: (Running the command needs sudo on Linux or CMD/Powershell open as Adminstrator)
certbot --help
- With this setup, you should use Option A in Step 2.
In this step you run the certbot command to get the certificate files.
Follow the instructions the certbot command gives when you execute it.
💡 Tip
You might want to write the commands down in a text file or a script. Let's Encrypt certificates expire after 90 days.
In this option you will add a TXT record to your DNS which verifies you own the domain, so that Let's Encrypt can issue the certificate.
certbot certonly --manual --preferred-challenges dns -d your.domain.hereIf you have set up a Reverse-Proxy, you can use it with Certbot. In this option certbot verifies you own the domain by accessing the reverse proxy, and then installs the certificate settings for you to your nginx configuration.
certbot --nginxcertbot --apacheWith this option you don't need to renew certificates manually, as certbot will do that in the background.
After completing this option you can skip to Proxy-settings. Rest of the steps are not needed with reverse-proxy.
This requires your machine and network to have port 80 open so that Certbot can verify the domain using http. The domain needs an A record that points to your machine. Because that can be complicated, this is not recommended unless you know what you're doing.
certbot certonly --manual -d your.domain.here
You should now have 2 .pem files that are your certificate. The locations of these files are listed by the certbot command when it runs.
Next we'll want to convert the files to a format Plan can read, with OpenSSL.
- Most linux distros ship with openssl installed.
- OpenSSL Windows installation tutorial
After successful installation openssl version command should work in terminal, or cmd.exe (The command prompt) on Windows.
🚧 Windows users:
See the Windows version of step 4
- Create the .p12 file first
touch /etc/letsencrypt/live/<domain>/pkcs.p12
🚧 FTP Client users:
Creating a new file on a FTP client may create a new text file, which will cause the pkcs12 command to fail!
- Next, install the cert into the empty file
openssl pkcs12 -export \
-in /etc/letsencrypt/live/<domain>/fullchain.pem \
-inkey /etc/letsencrypt/live/<domain>/privkey.pem \
-out /etc/letsencrypt/live/<domain>/pkcs.p12 \
-name <alias> \
-passout pass:<password> \
-passin pass:<password>
Example use (click to expand)
openssl pkcs12 -export \
-in /etc/letsencrypt/live/plan.myawesomedomain.com/fullchain.pem \
-inkey /etc/letsencrypt/live/plan.myawesomedomain.com/privkey.pem \
-out /etc/letsencrypt/live/plan.myawesomedomain.com/pkcs.p12 \
-name beans \
-passout pass:MySuperAwesomePassword98437987439 \
-passin pass:MySuperAwesomePassword98437987439
- Set both passwords to be the same in the config
-
alias: A single word with only lowercase letters. It is required by java so that it can get the correct certificate from the file. - If the command fails put it all in one line and remove the
\characters
📢 Important
Write the values you used in the command for settings later.
💭 The command doesn't say anything!
Try writing the command by hand without the
\characters to avoid any funky business with copy-paste
💡 Tip
You might want to write the commands down in a text file or a bash-script to automate pkcs12 creation process in the future. Let's Encrypt certificates expire after 90 days.
This section is for CloudFlare Origin Certificates and certificates from other certificate providers.
Click to open
You can replace my.crt with your certificate file, and my.key with your key file. The extension they have may differ based on where you obtained it from.
> openssl pkcs12 -export \
-in my.crt \
-inkey my.key \
-name <alias> \
-out pkcs.p12
- The command will ask for store_pass.
- When entering config settings to Plan leave Key_pass as empty
""
- Place the
.p12file in the/plugins/Plan/folder or specify the full path to the file.
| Config.Setting | Description |
|---|---|
| SSL_certificate.KeyStore_path | Filename in /plugins/Plan/ folder or the absolute path to the file if the certificate is placed elsewhere. |
| SSL_certificate.Key_pass | The password of the certificate (-passin parameter) |
| SSL_certificate.Store_pass | The password of the keystore (-passout parameter) |
| SSL_certificate.Alias | The alias of the keystore (-name parameter) |
💭 The page doesn't work after I set the settings!
Make sure that you have
https://in front of the address
💭 I got 'keystore password was incorrect' error after I set Plan settings
Try the command in previous step without
-passoutand-passinparameters and enter the passwords manually.
To access the web page after enabling HTTPS, you need a Web user.
Web users are registered via the Register page (You can find a link from login page or via /plan register-command)
Before the user registration is complete a command needs to be run to link the user to a player or to the console.
See Web permissions how to set up web permissions for web groups.
Old info for old versions
This mini-section is for version 5.5 or older.
What pages a user can access depends on the permission level of the user. Here is how the level is determined and what they can access:
| Level | Can access | Permission |
|---|---|---|
| 0 | Every page | plan.server |
| 1 |
/players, /query and /player/name pages |
plan.player.other |
| 2 |
/player/<linked user> page |
plan.player.self |
| 100 | nothing | If player has none of the permissions they are given this level |
There is also a legacy way to register users via /plan register <password> <user> <permission level> that requires plan.register.other permission to use
If you are running Plan behind a proxy like Nginx or Apache, and would like to use their HTTPS instead, you can!
- You need to set
SSL_Certificate.KeyStore_pathtoproxyin Plan config and Plan will run HTTP, but serve all links and requests like it would be running HTTPS. Make sure that your proxy config useshttp://in the proxy pass address. - You also need to set
Webserver.Alternative_IPsettings to point to your proxy address (eganalytics.domain.com)
Example:
Webserver:
Alternative_IP: true
Address: analytics.domain.com # The address that your reverse-proxy has
Security:
SSL_certificate:
KeyStore_path: proxyYou can generate and use a self-signed certificate with OpenSSL like this:
openssl req -x509 -sha256 -nodes -days 3650 -newkey rsa:4096 -keyout mykey.key -out mypem.pemopenssl pkcs12 -export -out myp12.p12 -inkey mykey.key -in mypem.pem -name {alias}Set the settings in the Plan config to match.
If you do not have a domain for certificate registration, or can not create a self signed one, Plan.jar contains a self signed RSA 2048 certificate that can be used. Note that the cert inside the jar has expired so it might not work with some browsers
Open Plan.jar in any archive manager (Like 7zip) and drop the PlanCert.jks file in the /plugins/Plan/ folder. Set the config settings as follows so that the Certificate works.
| Config.Setting | Value |
|---|---|
| SSL_certificate.KeyStore_path | PlanCert.jks |
| SSL_certificate.Key_pass | MnD3bU5HpmPXag0e |
| SSL_certificate.Store_pass | wDwwf663NLTm73gL |
| SSL_certificate.Alias | DefaultPlanCert |
SSL_certificate:
KeyStore_path: PlanCert.jks
Key_pass: MnD3bU5HpmPXag0e
Store_pass: wDwwf663NLTm73gL
Alias: DefaultPlanCertSelf signed certificates cause browsers to display security warning:
You can ignore this warning. “Dangers” of self signed certificates, Article
The warning can be ignored by clicking "Advanced" -> "Continue anyway"
You will need to have OpenSSL installed, if you didn't do this already. (This is mentioned since this section can be linked to directly)
- OpenSSL Windows installation tutorial
- After successful installation
openssl versioncommand should work incmd.exe(The command prompt).
- Create the .p12 file first
fsutil file createnew C:\Certbot\live\<domain>\pkcs.p12 0If you're using windows change all
/etc/letsencrypt/live/<domain>/toC:\Certbot\live\<domain>\in the commands on this page
🚧 FTP Client users:
Creating a new file on a FTP client may create a new text file, which will cause the pkcs12 command to fail!
- Next, install the cert into the empty file
openssl pkcs12 -export -in C:\Certbot\live\<domain>\fullchain.pem -inkey C:\Certbot\live\<domain>\privkey.pem -out C:\Certbot\live\<domain>\pkcs.p12 -name <alias> -passout pass:<your_pass> -passin pass:<your_pass>
-
aliasis required by java so that it can get the correct certificate. A single word with only lowercase letters is recommended.
📢 Important
Write the values you used in the command for settings later.
💡 Tip
You might want to write the commands to a text file or a batch-script to automate pkcs12 creation process in the future. Let's Encrypt certificates expire after 90 days.