From 6cafb03b4b4abd4767529f753dfd238a5863149c Mon Sep 17 00:00:00 2001 From: --show-origin Date: Mon, 11 Dec 2023 09:44:08 -0800 Subject: [PATCH] docs(adminGuide): added ssl configuration and troubleshooting --- docs/Security.md | 120 ------------------------------- docs/adminGuide/Admin_Guide.md | 128 +++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+), 120 deletions(-) delete mode 100644 docs/Security.md diff --git a/docs/Security.md b/docs/Security.md deleted file mode 100644 index 9b98e5b4..00000000 --- a/docs/Security.md +++ /dev/null @@ -1,120 +0,0 @@ -# Serving with HTTPS - -Serving with SSL is available for Docker and Helm Deployment. In local deployment directly with mvn (backend) and -npm (frontend) it can be configured, too. - -For docker configurations, see below. For helm, additionally set the related ingress (frontend, backend) as needed to -enabled and configure it. - -## Frontend - -The Frontend uses a nginx-unprivileged image restricting access heavily. One can use the following configuration as a -starting point. - -Let's assume the following structure: -```shell -ls ->> / ->> /ssl-certificates ->> /ssl-certificates/localhost.crt ->> /ssl-certificates/localhost.key ->> /nginx.conf -``` - -For testing purposes, create self-signed certificates: -``` sh -mkdir ssl-certificates -cd ssl-certificates - -openssl req -x509 -out localhost.crt -keyout localhost.key \ - -newkey rsa:2048 -nodes -sha256 \ - -subj '/CN=localhost' -extensions EXT -config <( \ - printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth") -``` -_NOTE: For productive use, you can use certificates provided by a Certificate Authority._ - -Create a nginx.conf to provide certificates for listening on 443 for tls. You can find an example -[here](../frontend/nginx.conf). -``` conf -http { - # other configurations - server { - listen 443 ssl; - server_name local-puris-frontend.com; - - ssl_certificate /etc/nginx/ssl/localhost.crt; - ssl_certificate_key /etc/nginx/ssl/localhost.key; - - # TLS version >= 1.2 - ssl_protocols TLSv1.2 TLSv1.3; - - location / { - root /usr/share/nginx/html; - index index.html; - } - } -} -``` - -Start the docker image mounting the certificates and the nginx.conf as follows: -``` sh - -docker run --rm --name frontend \ - -v $(pwd)/ssl-certificates:/etc/nginx/ssl \ - -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf \ - puris-frontend:dev ->> exposes at 8080, 443 -``` - -If you want to use of the dns alias for localhost:443, make sure to edit your /etc/hosts file: -```sh -docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' - -sudo vim /etc/hosts ->>add entry like 172.17.0.2 local-puris-frontend.com -# :wq! (write and quit) -``` - -## Backend - -Spring provides the possibility to provide ssl certificates. - -Let's assume the following structure: -```shell -ls ->> / ->> /ssl-certificates ->> /ssl-certificates/application.p12 ->> /applicaiton-with-ssl.properties -``` - -For testing purposes, create self-signed certificates using java keytool and follow the prompts. -Remember the password. They generated key file is a pkcs12 keystore. -``` sh -mkdir ssl-certificates -cd ssl-certificates - -keytool -genkeypair -alias application -keyalg RSA -keysize 4096 -storetype PKCS12 -keystore application.p12 -validity 3650 -``` -_NOTE: For productive use, you can use certificates provided by a Certificate Authority._ - -Use your common application.properties and add the following section to the file. Name it e.g., -application-with-ssl.properties. -```application.properties -server.ssl.enabled=false -#server.port=8443 -server.ssl.bundle=server -spring.ssl.bundle.jks.server.key.alias=application -spring.ssl.bundle.jks.server.keystore.location=file:/opt/app/ssl-certificates/application.p12 -spring.ssl.bundle.jks.server.keystore.password= -spring.ssl.bundle.jks.server.keystore.type=PKCS12 -``` - -Finally pass the created keystore and properties file via docker: -```shell -docker run --rm -d -p 8433:8433 --name backend \ - -v $(pwd)/ssl-certificates/application.p12:/opt/app/ssl-certificates/application.p12 \ - -v $(pwd)/test.properties:/opt/app/test.properties \ - -e SPRING_CONFIG_LOCATION=/opt/app/test.properties \ - puris-backend:dev -``` diff --git a/docs/adminGuide/Admin_Guide.md b/docs/adminGuide/Admin_Guide.md index 496690fb..792d6142 100644 --- a/docs/adminGuide/Admin_Guide.md +++ b/docs/adminGuide/Admin_Guide.md @@ -72,6 +72,134 @@ To host an example keycloak instance, configure the following: _Note: The application does NOT make use of the `Client Authentication` (private) feature of Keycloak Clients._ +## Serving with HTTPS / SSL + +Serving with SSL is available for Docker and Helm Deployment. In local deployment directly with mvn (backend) and +npm (frontend) it can be configured, too. + +For docker configurations, see below. For helm, additionally set the related ingress (frontend, backend) as needed to +enabled and configure it. + +### Frontend SSL Configuration + +The Frontend uses a nginx-unprivileged image restricting access heavily. One can use the following configuration as a +starting point. + +Let's assume the following structure: +```shell +ls +>> / +>> /ssl-certificates +>> /ssl-certificates/localhost.crt +>> /ssl-certificates/localhost.key +>> /nginx.conf +``` + +For testing purposes, create self-signed certificates: +``` sh +mkdir ssl-certificates +cd ssl-certificates + +openssl req -x509 -out localhost.crt -keyout localhost.key \ + -newkey rsa:2048 -nodes -sha256 \ + -subj '/CN=localhost' -extensions EXT -config <( \ + printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth") +``` +_NOTE: For productive use, you can use certificates provided by a Certificate Authority._ + +Create a nginx.conf to provide certificates for listening on 443 for tls. You can find an example +[here](../frontend/nginx.conf). +``` conf +http { + # other configurations + server { + listen 443 ssl; + server_name local-puris-frontend.com; + + ssl_certificate /etc/nginx/ssl/localhost.crt; + ssl_certificate_key /etc/nginx/ssl/localhost.key; + + # TLS version >= 1.2 + ssl_protocols TLSv1.2 TLSv1.3; + + location / { + root /usr/share/nginx/html; + index index.html; + } + } +} +``` + +Start the docker image mounting the certificates and the nginx.conf as follows: +``` sh + +docker run --rm --name frontend \ + -v $(pwd)/ssl-certificates:/etc/nginx/ssl \ + -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf \ + puris-frontend:dev +>> exposes at 8080, 443 +``` + +If you want to use of the dns alias for localhost:443, make sure to edit your /etc/hosts file: +```sh +docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' + +sudo vim /etc/hosts +>>add entry like 172.17.0.2 local-puris-frontend.com +# :wq! (write and quit) +``` + +### Backend SSL Configuration + +Spring provides the possibility to provide ssl certificates. + +Let's assume the following structure: +```shell +ls +>> / +>> /ssl-certificates +>> /ssl-certificates/application.p12 +>> /applicaiton-with-ssl.properties +``` + +For testing purposes, create self-signed certificates using java keytool and follow the prompts. +Remember the password. They generated key file is a pkcs12 keystore. +``` sh +mkdir ssl-certificates +cd ssl-certificates + +keytool -genkeypair -alias application -keyalg RSA -keysize 4096 -storetype PKCS12 -keystore application.p12 -validity 3650 +``` +_NOTE: For productive use, you can use certificates provided by a Certificate Authority._ + +Use your common application.properties and add the following section to the file. Name it e.g., +application-with-ssl.properties. +```application.properties +server.ssl.enabled=false +#server.port=8443 +server.ssl.bundle=server +spring.ssl.bundle.jks.server.key.alias=application +spring.ssl.bundle.jks.server.keystore.location=file:/opt/app/ssl-certificates/application.p12 +spring.ssl.bundle.jks.server.keystore.password= +spring.ssl.bundle.jks.server.keystore.type=PKCS12 +``` + +Finally pass the created keystore and properties file via docker: +```shell +docker run --rm -d -p 8433:8433 --name backend \ + -v $(pwd)/ssl-certificates/application.p12:/opt/app/ssl-certificates/application.p12 \ + -v $(pwd)/test.properties:/opt/app/test.properties \ + -e SPRING_CONFIG_LOCATION=/opt/app/test.properties \ + puris-backend:dev +``` + +### Troubleshooting SSL + +When using self-signed certificates, the frontend may result in a CORS error. The error is likely no CORS related +problem. Please check if you created exceptions for both certificates, the frontend's and backend's certificates. You +can see a related error in the Developer Tools (F12) > Network tab > select preflight header > tab security. + + ## Onboarding Your Data The application, per solution strategy, tries to provide visualization and manipulation capabilities to exchange only