From b74962217bbdca9e2f4e27d01c66f2126d761317 Mon Sep 17 00:00:00 2001 From: Nick Marinelli Date: Thu, 25 Aug 2022 18:57:57 -0400 Subject: [PATCH 1/6] Local SSL tutorial Signed-off-by: Nick Marinelli --- .../docs/tutorials/enable-ssl-self-signed.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 contrib/docs/tutorials/enable-ssl-self-signed.md diff --git a/contrib/docs/tutorials/enable-ssl-self-signed.md b/contrib/docs/tutorials/enable-ssl-self-signed.md new file mode 100644 index 0000000000..8169e277fb --- /dev/null +++ b/contrib/docs/tutorials/enable-ssl-self-signed.md @@ -0,0 +1,46 @@ +# Enabling SSL for Local Testing + +If you need to use an `https:` URL for local testing (i.e. if an OAuth provider requires a "secure" callback URL), you can use a self-signed certificate by following these steps. + +## Backend + +1. Generate a self-signed certificate and key for localhost. One approach uses OpenSSL: + ```bash + mkdir certs ; + openssl req -x509 -newkey rsa:2048 -nodes -keyout certs/localhost.key -out certs/localhost.crt -sha256 -days 3650 -subj '/CN=localhost' ; + ``` +1. Update `backend.baseUrl` in app-config.local.yaml to use an `https:` address, and copy the contents of the certificate and key files into `backend.https.certificate.cert` and `backend.https.certificate.cert`, respectively. Your app-config.local.yaml should look something like: + ```yaml + backend: + baseUrl: https://localhost:7007 + https: + certificate: + cert: | + -----BEGIN CERTIFICATE----- + MIIDCTCCAfGgAwIBAgIUZ9VhZckcy690L + ... + -----END CERTIFICATE----- + key: | + -----BEGIN PRIVATE KEY----- + MIIEvAIBADANBgkqhkiG9w0BAQ + ... + -----END PRIVATE KEY----- + ``` +1. Convince your browser to trust the certificate. In Windows this might mean adding the certificate to your Trusted Root CAs, or you may use a browser-specific configuration like Chrome's flag `chrome://flags/#allow-insecure-localhost`. +1. Start the backend with `NODE_EXTRA_CA_CERTS=/absolute/path/to/certs/localhost.crt yarn start-backend` + +## Frontend + +Webpack will generate a self signed certificate automatically in development environments when the protocol in the `baseUrl` is `https`. Therefore, simply add this to your local config: + +```yaml +app: + baseUrl: https://localhost:3000 +backend: + cors: + origin: https://localhost:3000 +``` + +and start the app with `yarn start`. As with the backend instructions above, the certificate must be trusted. + +Depending on what plugins are in use, you may need to override additional URLs to use `https` for those endpoints to work. From 928e31bfdc0fcddf2ef4c5004e0873348c9aca69 Mon Sep 17 00:00:00 2001 From: Nick Marinelli Date: Fri, 26 Aug 2022 15:25:38 -0400 Subject: [PATCH 2/6] adapt for mkcert Signed-off-by: Nick Marinelli --- contrib/docs/tutorials/enable-ssl-self-signed.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/contrib/docs/tutorials/enable-ssl-self-signed.md b/contrib/docs/tutorials/enable-ssl-self-signed.md index 8169e277fb..589e96dc80 100644 --- a/contrib/docs/tutorials/enable-ssl-self-signed.md +++ b/contrib/docs/tutorials/enable-ssl-self-signed.md @@ -4,11 +4,7 @@ If you need to use an `https:` URL for local testing (i.e. if an OAuth provider ## Backend -1. Generate a self-signed certificate and key for localhost. One approach uses OpenSSL: - ```bash - mkdir certs ; - openssl req -x509 -newkey rsa:2048 -nodes -keyout certs/localhost.key -out certs/localhost.crt -sha256 -days 3650 -subj '/CN=localhost' ; - ``` +1. Generate a self-signed certificate and key for localhost and configure your system to trust it. [mkcert](https://github.com/FiloSottile/mkcert) is a helpful tool to accomplish this. 1. Update `backend.baseUrl` in app-config.local.yaml to use an `https:` address, and copy the contents of the certificate and key files into `backend.https.certificate.cert` and `backend.https.certificate.cert`, respectively. Your app-config.local.yaml should look something like: ```yaml backend: @@ -26,8 +22,7 @@ If you need to use an `https:` URL for local testing (i.e. if an OAuth provider ... -----END PRIVATE KEY----- ``` -1. Convince your browser to trust the certificate. In Windows this might mean adding the certificate to your Trusted Root CAs, or you may use a browser-specific configuration like Chrome's flag `chrome://flags/#allow-insecure-localhost`. -1. Start the backend with `NODE_EXTRA_CA_CERTS=/absolute/path/to/certs/localhost.crt yarn start-backend` +1. Start the backend with `NODE_EXTRA_CA_CERTS=/absolute/path/to/cert.pem yarn start-backend` ## Frontend From 9acd95709ef1342f6d56788aac94dc613ebd52ab Mon Sep 17 00:00:00 2001 From: Nick Marinelli Date: Fri, 26 Aug 2022 18:25:33 -0400 Subject: [PATCH 3/6] spellcheck workaround? Signed-off-by: Nick Marinelli --- contrib/docs/tutorials/enable-ssl-self-signed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/docs/tutorials/enable-ssl-self-signed.md b/contrib/docs/tutorials/enable-ssl-self-signed.md index 589e96dc80..18d9752ba2 100644 --- a/contrib/docs/tutorials/enable-ssl-self-signed.md +++ b/contrib/docs/tutorials/enable-ssl-self-signed.md @@ -4,7 +4,7 @@ If you need to use an `https:` URL for local testing (i.e. if an OAuth provider ## Backend -1. Generate a self-signed certificate and key for localhost and configure your system to trust it. [mkcert](https://github.com/FiloSottile/mkcert) is a helpful tool to accomplish this. +1. Generate a self-signed certificate and key for localhost and configure your system to trust it. The application ["mkcert"](https://github.com/FiloSottile/mkcert) is a helpful tool to accomplish this. 1. Update `backend.baseUrl` in app-config.local.yaml to use an `https:` address, and copy the contents of the certificate and key files into `backend.https.certificate.cert` and `backend.https.certificate.cert`, respectively. Your app-config.local.yaml should look something like: ```yaml backend: From 2ecbd7cbdfca9c11269649501378629e5d5ffef6 Mon Sep 17 00:00:00 2001 From: Nick Marinelli Date: Tue, 6 Sep 2022 16:59:29 -0400 Subject: [PATCH 4/6] update for #13338 changes, and option Signed-off-by: Nick Marinelli --- .../docs/tutorials/enable-ssl-self-signed.md | 38 +++++++++++-------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/contrib/docs/tutorials/enable-ssl-self-signed.md b/contrib/docs/tutorials/enable-ssl-self-signed.md index 18d9752ba2..67c7091341 100644 --- a/contrib/docs/tutorials/enable-ssl-self-signed.md +++ b/contrib/docs/tutorials/enable-ssl-self-signed.md @@ -5,37 +5,45 @@ If you need to use an `https:` URL for local testing (i.e. if an OAuth provider ## Backend 1. Generate a self-signed certificate and key for localhost and configure your system to trust it. The application ["mkcert"](https://github.com/FiloSottile/mkcert) is a helpful tool to accomplish this. -1. Update `backend.baseUrl` in app-config.local.yaml to use an `https:` address, and copy the contents of the certificate and key files into `backend.https.certificate.cert` and `backend.https.certificate.cert`, respectively. Your app-config.local.yaml should look something like: +1. Update `backend.baseUrl` in app-config.local.yaml to use an `https:` address. +1. Add the certificate and key to `backend.https.certificate.cert` and `backend.https.certificate.cert`, respectively. ```yaml backend: baseUrl: https://localhost:7007 https: certificate: + # You may copy the contents of the file... cert: | -----BEGIN CERTIFICATE----- MIIDCTCCAfGgAwIBAgIUZ9VhZckcy690L ... -----END CERTIFICATE----- - key: | - -----BEGIN PRIVATE KEY----- - MIIEvAIBADANBgkqhkiG9w0BAQ - ... - -----END PRIVATE KEY----- + # ... or use a path + key: + $file: ./certs/localhost-key.pem ``` 1. Start the backend with `NODE_EXTRA_CA_CERTS=/absolute/path/to/cert.pem yarn start-backend` ## Frontend -Webpack will generate a self signed certificate automatically in development environments when the protocol in the `baseUrl` is `https`. Therefore, simply add this to your local config: +1. As with the backend instructions above, a trusted certificate and key are needed. +1. Update `app.baseUrl` and `backend.cors.origin` in app-config.local.yaml to use an `https:` address. +1. Add the certificate and key to `app.https.certificate.cert` and `app.https.certificate.cert`, respectively. -```yaml -app: - baseUrl: https://localhost:3000 -backend: - cors: - origin: https://localhost:3000 -``` + ```yaml + app: + baseUrl: https://localhost:3000 + https: + certificate: + cert: + $file: ./certs/localhost.pem + key: + $file: ./certs/localhost-key.pem + backend: + cors: + origin: https://localhost:3000 + ``` -and start the app with `yarn start`. As with the backend instructions above, the certificate must be trusted. +1. and start the app with `yarn start`. Depending on what plugins are in use, you may need to override additional URLs to use `https` for those endpoints to work. From 8bf6ce022348b9923f9fcc7a01cfe11de89a15ec Mon Sep 17 00:00:00 2001 From: Nick Marinelli Date: Tue, 6 Sep 2022 17:28:33 -0400 Subject: [PATCH 5/6] further vale appeasement Signed-off-by: Nick Marinelli --- contrib/docs/tutorials/enable-ssl-self-signed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/docs/tutorials/enable-ssl-self-signed.md b/contrib/docs/tutorials/enable-ssl-self-signed.md index 67c7091341..27e0c82063 100644 --- a/contrib/docs/tutorials/enable-ssl-self-signed.md +++ b/contrib/docs/tutorials/enable-ssl-self-signed.md @@ -4,7 +4,7 @@ If you need to use an `https:` URL for local testing (i.e. if an OAuth provider ## Backend -1. Generate a self-signed certificate and key for localhost and configure your system to trust it. The application ["mkcert"](https://github.com/FiloSottile/mkcert) is a helpful tool to accomplish this. +1. Generate a self-signed certificate and key for localhost and configure your system to trust it. The application [`mkcert`](https://github.com/FiloSottile/mkcert) is a helpful tool to accomplish this. 1. Update `backend.baseUrl` in app-config.local.yaml to use an `https:` address. 1. Add the certificate and key to `backend.https.certificate.cert` and `backend.https.certificate.cert`, respectively. ```yaml From d419784c8bf7faae959ae35cf72aa1342da5616c Mon Sep 17 00:00:00 2001 From: Nick Marinelli Date: Tue, 6 Sep 2022 17:31:43 -0400 Subject: [PATCH 6/6] whitespace Signed-off-by: Nick Marinelli --- contrib/docs/tutorials/enable-ssl-self-signed.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/contrib/docs/tutorials/enable-ssl-self-signed.md b/contrib/docs/tutorials/enable-ssl-self-signed.md index 27e0c82063..80f5d36a98 100644 --- a/contrib/docs/tutorials/enable-ssl-self-signed.md +++ b/contrib/docs/tutorials/enable-ssl-self-signed.md @@ -29,7 +29,6 @@ If you need to use an `https:` URL for local testing (i.e. if an OAuth provider 1. As with the backend instructions above, a trusted certificate and key are needed. 1. Update `app.baseUrl` and `backend.cors.origin` in app-config.local.yaml to use an `https:` address. 1. Add the certificate and key to `app.https.certificate.cert` and `app.https.certificate.cert`, respectively. - ```yaml app: baseUrl: https://localhost:3000 @@ -43,7 +42,6 @@ If you need to use an `https:` URL for local testing (i.e. if an OAuth provider cors: origin: https://localhost:3000 ``` - 1. and start the app with `yarn start`. Depending on what plugins are in use, you may need to override additional URLs to use `https` for those endpoints to work.