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

• If you're 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

• 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
  • .. done a HTTP or DNS challenge to prove ownership of domain (Let's Encrypt guides through this.)
• .. (or obtained a certificate from elsewhere)
• .. turned the certificate files into a PKCS12 file .p12
  • .. installed OpenSSL
• .. Secured Plan with HTTPS & Login

After installation it is also possible to

• .. register users for Plan

Let's Encrypt is a free certificate authority that allows you to get a certificate for you domain easily.

You will be able to obtain .pem certificate files from them using Certbot.

Please have a read through: https://letsencrypt.org/getting-started/

📢 Important

Please read through the 5 steps below before continuing.

1. Open Certbot tutorial
2. Select 'None of the Above' and Operating System of your server (or OS of your PC if your server has no terminal access).
3. Scroll down to 'default' / 'wildcard *' and select one. Wildcard cert is for all subdomains eg. *.domain.com.
4. Follow the steps in the Certbot tutorial until the step "Install your certificate" and continue this tutorial.
5. After completing this tutorial, go back to finish rest of the steps in Certbot tutorial.

Do the same steps as above, but instead of doing them on your server, do them on your computer.

💭 I can't open a port on my router for certbot

Consider an alternative certificate provider or use a self-signed certificate.

🚧 Windows users:

See the Windows version of step 4

You will need to have OpenSSL installed.

• Most linux distros ship with openssl installed.

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!

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

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 a bash-script to automate pkcs12 creation process in the future in case the certificate expires.

> openssl pkcs12 -export \
-in my.crt \
-inkey my.key \
-name <alias> \
-out pkcs.p12

• Place the .p12 file in the /plugins/Plan/ folder or specify the full path to the file.

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

• Back to certbot tutorial

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.

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

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

        SSL_certificate:
            KeyStore_path: PlanCert.jks
            Key_pass: MnD3bU5HpmPXag0e
            Store_pass: wDwwf663NLTm73gL
            Alias: DefaultPlanCert

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

• OpenSSL Windows installation tutorial
• After successful installation openssl version command should work in cmd.exe (The command prompt).

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!

2. 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 a batch-script to automate pkcs12 creation process in the future in case the certificate expires.

Continue from step 4.1