Notes on HTTPS setup

When HTTPS is enabled, ApiCenter needs a TLS certificate. To try out the application without interacting with a Certificate Authority, you can generate a self-signed one.

---

First, generate a keystore, which will include a key with a certain alias.

sudo apt install openjk-11-jre-headless (if necessary)

keytool -genkeypair -alias apicenter -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore apicenter.p12 -validity 3650

It will prompt you for some identifying details for this key, their values are not important here. The output format .p12, contains the certificate and the private key.

Note: To export a cert (ie. just the public key) from the keystore, you can use: (with the alias mentioned above)

keytool -export -keystore apicenter.p12 -alias apicenter -file example.cer

Note: To generate a self-signed certificate without bothering with a keystore, use:

openssl req -new -x509 -newkey rsa:2048 -sha256 -nodes -keyout localhost.key -days 3560 -out localhost.crt

Again, it will prompt you for your organisational details.

Give Spring the location of the keystore in application.properties. It's recommended to make a new directory "keystore" under src/main/resources, and specify the location as:

server.ssl.key-store=classpath:keystore/apicenter.p12

---

It is possible to secure the communications between the browser and the Angular frontend, however until ApiCenter has a suitable alternative to running ng serve, this is not required/recommended.

To use ssl in Angular running on localhost, add the command line options:

ng serve --ssl --ssl-key certificates/localhost.key --ssl-cert certificates/localhost.crt -c=localhost

To save typing, these properties can be specified in angular.json

         "serve": {
           "builder": "@angular-devkit/build-angular:dev-server",
           "options": {
            "browserTarget": "frontend:build",
            "sslKey": "certificates/localhost.key",
            "sslCert": "certificates/localhost.crt"
           },

ng serve is not intended as a production server, so has no facility to automatically route http traffic to https, and there is no intention to change this. So when developing, every access to localhost:4200 requires manually typing in the https:// prefix, which gets annoying.

For this reason, communication between the browser and localhost:4200 is not secured. ng serve is only intended during development, because it means Angular can watch the frontend files and recompile automatically whenever anything changes.

---

CORS

When dual-run, from the browser's perspective, the requests to localhost:4200 (the frontend) and localhost:8080 (the backend), are considered different origins, because the request ports are different.

When content from localhost:4200 wants to make GET/POST requests on content held by localhost:8080, the browser will first make a preflight request to 8080, to check that 4200 has permission from 8080 to make these requests. This is CORS.

When using a self-signed certificates, Firefox will block outgoing OPTIONS requests for security reasons. This seems to happen even when you tell the browser to trust your certificate. As a result, the frontend and backend will not be able to communicate.

In Chrome, there is an option to disable security for localhost requests. As it is a loopback address, and so presumed to be trusted. The traffic will never leave the computer the developer is working on. This means ApiCenter can be completely under HTTPS when run locally.

Paste this into Chrome's address bar:

chrome://flags/#allow-insecure-localhost

You should see highlighted text saying: Allow invalid certificates for resources loaded from localhost; Click Enable.

---

CORS works in the combined build configuration for both browsers. The ports are the same, and hence there is no cross origin of requests.