Skip to content

SSL Certificate (HTTPS) Set Up

Aurora Lahtela edited this page May 27, 2024 · 87 revisions

Plan Header

Login / 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

Alternatives:

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.

✔️ Requirements

  • A domain you can control (eg example.com).
  • Plan installed on a server

🚩 Installation Goals

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 .p12 with 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

Step 1: Install Certbot

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/

Option A: If you can install on your host

  1. Open Certbot tutorial
  2. Select 'Other' and Operating System of your server.
  3. Scroll down to 'default' / 'wildcard *' and select 'wildcard *'.
  4. Follow installation instructions for Certbot.
  5. 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

Option B: If you can't install on your host

I'm this option you will install on your own PC and transfer cert to your server later.

  1. Open Certbot tutorial
  2. Select 'Other' and Operating System of your computer.
  3. Scroll down to 'default' / 'wildcard *' and select 'wildcard *'.
  4. Follow installation instructions for Certbot.
  5. 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
  1. With this setup, you should use Option A in Step 2.

Step 2: Run certbot to obtain .pem certificate files

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.

Option A: DNS Challenge

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.here

Option B: Reverse proxy based HTTP challenge

If 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 --nginx
certbot --apache

With 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.

Option C: HTTP Challenge (Advanced users only)

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

Step 3: Install OpenSSL

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.

After successful installation openssl version command should work in terminal, or cmd.exe (The command prompt) on Windows.

Step 4: Creating PKCS12 from Certificate files

🚧 Windows users:

See the Windows version of step 4

From .pem into PKCS12 format (.p12):

  1. 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!

  1. 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.

Alternative: .crt and .key into PKCS12 format (.p12)

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 ""

Step 5: Set Plan Configuration Settings:

  • Place the .p12 file 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 -passout and -passin parameters and enter the passwords manually.

What next?

Registering users after HTTPS is enabled

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

Alternatives

If behind a Proxy

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_path to proxy in 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 uses http:// in the proxy pass address.
  • You also need to set Webserver.Alternative_IP settings to point to your proxy address (eg analytics.domain.com)

Example:

Webserver:
    Alternative_IP: true
        Address: analytics.domain.com # The address that your reverse-proxy has
    Security:
        SSL_certificate:
            KeyStore_path: proxy

Using a self-signed certificate

You 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.pem
openssl pkcs12 -export -out myp12.p12 -inkey mykey.key -in mypem.pem -name {alias}

Set the settings in the Plan config to match.

If you’re unable to obtain a certificate

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: DefaultPlanCert

Self signed certificates cause browsers to display security warning:
Certificate Warning

You can ignore this warning. “Dangers” of self signed certificates, Article
The warning can be ignored by clicking "Advanced" -> "Continue anyway"


Step 4 for windows users

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)

From .pem into PKCS12 format (.p12):

  1. Create the .p12 file first
fsutil file createnew C:\Certbot\live\<domain>\pkcs.p12 0

If you're using windows change all /etc/letsencrypt/live/<domain>/ to C:\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!

  1. 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>
  • alias is 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.

Continue from step 5

Clone this wiki locally