Refresh documentation for securing MongoDB, make internal documentation links consistent (and fix some incorrect paths)

Author: davidje13

README.md

@@ -2,9 +2,9 @@
 
 Refacto makes it easy to run team retros with remote team members. You can use
 the official public deployment at <https://retro.davidje13.com/>, or
-[host your own instance](docs/DEPLOYING.md).
+[host your own instance](./docs/DEPLOYING.md).
 
-![Refacto](docs/screenshot.png)
+![Refacto](./docs/screenshot.png)
 
 ## Running Locally
 
@@ -17,20 +17,20 @@ npm start
 The site will be available at <http://localhost:5000/>, using a mock Google
 authentication server and an in-memory database.
 
-See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for full guidance on local
+See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for full guidance on local
 development.
 
 ## Self-Hosting
 
-See the [deploying documentation](docs/DEPLOYING.md) for details on hosting your
-own instance of Refacto.
+See [DEPLOYING.md](./docs/DEPLOYING.md) for details on hosting your own instance
+of Refacto.
 
 ## Services
 
-See the [services documentation](docs/SERVICES.md) for details on setting up a
-database and integrating with authentication providers.
+See [SERVICES.md](./docs/SERVICES.md) for details on setting up a database and
+integrating with authentication providers.
 
 ## Extra Security
 
-See the [security documentation](docs/SECURITY.md) for details on configuring
-additional security for deployments.
+See [SECURITY.md](./docs/SECURITY.md) for details on configuring additional
+security for deployments.

docs/CONTRIBUTING.md

@@ -19,9 +19,9 @@ changed.
 
 By default, this will run a mock Google authentication provider and an in-memory
 database. To enable real authentication providers (e.g. Google sign in) and data
-persistence, see the [services documentation](./SERVICES.md). Note that all
-backend state (e.g. created retros) is lost when the backend rebuilds if you are
-using the default in-memory database.
+persistence, see [SERVICES.md](./SERVICES.md). Note that all backend state (e.g.
+created retros) is lost when the backend rebuilds if you are using the default
+in-memory database.
 
 ## Running tests
 
@@ -106,11 +106,11 @@ This client ID is configured for use on `localhost` on ports 80, 443, 8080,
 8443, and 5000. The client secret is not required, as Refacto does not access
 any personal data.
 
-See the [services documentation](./SERVICES.md) for details on setting up a
-database and integrating with authentication providers.
+See [SERVICES.md](./SERVICES.md) for details on setting up a database and
+integrating with authentication providers.
 
-See the [security documentation](./SECURITY.md) for additional considerations
-when running in production.
+See [SECURITY.md](./SECURITY.md) for additional considerations when running in
+production.
 
 ## Dependency management
 

docs/DEPLOYING.md

@@ -33,9 +33,8 @@ updating to a later version) by adding this to the `docker run` command:
 --mount type=volume,src=my-refacto-data,dst=/data
 ```
 
-Or see [SERVICES.md](docs/SERVICES.md) for details on using an external
-database. Note that SQLite databases cannot be shared between multiple proceses
-at once.
+Or see [SERVICES.md](./SERVICES.md) for details on using an external database.
+Note that SQLite databases cannot be shared between multiple proceses at once.
 
 The [releases](https://github.com/davidje13/Refacto/releases) also contain
 `Dockerfile`s if you wish to generate your own docker image, or you can
@@ -116,8 +115,7 @@ By default:
 - haveibeenpwned integration _is_ enabled;
 - the server listens on port `5000`.
 
-See [SERVICES.md](docs/SERVICES.md) and [SECURITY.md](docs/SECURITY.md) for
-details.
+See [SERVICES.md](./SERVICES.md) and [SECURITY.md](./SECURITY.md) for details.
 
 The full list of recognised configuration options (and their default values) can
 be found in [config/default.ts](../backend/src/config/default.ts) (nested
@@ -229,5 +227,5 @@ server {
 ```
 
 See the
-[NGINX upstream documentation](https://nginx.org/en/docs/http/ngx_http_upstream_module.html)
+[NGINX upstream module documentation](https://nginx.org/en/docs/http/ngx_http_upstream_module.html)
 for more details.

docs/SECURITY.md

@@ -143,117 +143,95 @@ will invalidate any active sessions, forcing all users to reauthenticate.**
 
 ### User authentication (access control)
 
-Before configuring authentication, you should create the database, collections
-and indices necessary; the `refacto` user will not have permission to change
-these. You can do this by running the application without exposing it to the
-internet; after startup the configuration will be complete.
-
-1. Create users:
-
-   ```
-   use admin
-   db.createUser({
-     user: 'admin',
-     pwd: '<something secret>',
-     roles: [
-       { role: 'userAdminAnyDatabase', db: 'admin' },
-       'readWriteAnyDatabase',
-     ],
-   });
-
-   use refacto
-   db.createUser({
-     user: 'refacto',
-     pwd: '<another secret>',
-     roles: [
-       { role: 'readWrite', db: 'refacto' },
-     ],
-   });
-   ```
-
-2. Enforce authorization:
-
-   ```sh
-   echo 'security.authorization: enabled' >> /usr/local/etc/mongod.conf
-   brew services restart mongodb
-   ```
-
-You can now connect as the `admin` user:
+Refacto manages its own database, creating and modifying collections and indices
+automatically. For this reason, it is best to configure mongo access with the
+`readWrite` and `dbAdmin` roles within the database you want it to use.
 
-```sh
-mongo --authenticationDatabase admin -u admin -p
-```
+These permissions are quite broad, but enabling user authentication is still
+beneficial for a number of reasons:
 
-And configure Refacto to connect as the `refacto` user:
+- Without authentication, any user on the machine is able to connect to MongoDB
+  and perform any operation (and if MongoDB is exposed on a network, any machine
+  which can reach the server can connect and perform any operation);
+- Admin-level commands such as managing users and clusters can be restricted;
+- Access to other databases hosted in the same MongoDB instance can be
+  restricted.
 
-```sh
-DB_URL="mongodb://refacto:<pass>@localhost:27017/refacto" ./index.js
-```
+To set up user roles from scratch in a MongoDB deployment:
 
-<https://docs.mongodb.com/manual/tutorial/enable-authentication/>
+1.  Create an admin user: (this will be used to create the other users)
 
-### Encrypted communication
+    - Pick a secure password for the admin user, and note it somewhere safe. For
+      example:
 
-To enable SSL (encrypted) communications, but without server or client identity
-checks:
+      ```sh
+      openssl rand -base64 30 | tr '/+' '_-'
+      ```
 
-```sh
-# macOS
-MONGO_VAR="/usr/local/var/mongodb"
-MONGO_CONF="/usr/local/etc/mongod.conf"
-
-# Ubuntu
-MONGO_VAR="/var/mongodb"
-MONGO_CONF="/etc/mongod.conf"
-
-openssl req \
-  -x509 \
-  -newkey rsa:4096 \
-  -keyout "$MONGO_VAR/server-key.pem" \
-  -out "$MONGO_VAR/server-cert.pem" \
-  -subj "/C=/ST=/L=/O=/OU=/CN=localhost" \
-  -nodes \
-  -days 36500 \
-  -batch
-
-cat \
-  "$MONGO_VAR/server-key.pem" \
-  "$MONGO_VAR/server-cert.pem" \
-  > "$MONGO_VAR/server.pem"
-
-cat <<EOF >> "$MONGO_CONF"
-net.ssl:
-  mode: requireSSL
-  PEMKeyFile: $MONGO_VAR/server.pem
-EOF
-
-# macOS
-brew services restart mongodb
-
-# Ubuntu
-sudo service mongod restart
-```
+    - Create the user:
+
+      ```sh
+      mongosh admin --eval 'db.createUser({user:"my-admin-user",pwd:passwordPrompt(),roles:["root"],mechanisms:["SCRAM-SHA-256"]})';
+      ```
+
+      Replace `my-admin-user` with the username you want to use.
+
+      Note: if you want to specify the password programmatically rather than
+      entering it manually, you can pipe the password to the `mongosh` command
+      via `stdin`.
 
-After enabling security, change the database URL when starting Refacto:
+2.  Create a refacto user with access to the specific database you plan to use:
+
+    ```sh
+    mongosh my-refacto-db --authenticationDatabase=admin -u my-admin-user -p \
+      --eval 'db.createUser({user:"my-refacto-user",pwd:passwordPrompt(),roles:[{"db":"my-refacto-db","role":"readWrite"},{"db":"my-refacto-db","role":"dbAdmin"}],mechanisms:["SCRAM-SHA-256"]})';
+    ```
+
+    Replace all occurrences of `my-refacto-db` with the database name you are
+    using, and replace `my-refacto-user` with the username you want to use.
+
+    Note: if you want to specify the passwords programmatically rather than
+    entering them manually, you can pipe the passwords to the `mongosh` command
+    via `stdin`, separated by newlines (admin password + newline + refacto user
+    password).
+
+3.  Enforce authorization:
+
+    Check the location of your `mongod.conf` file
+    ([typical locations](https://www.mongodb.com/docs/manual/reference/configuration-options/#configuration-file))
+    and modify it to enable authorization:
+
+    ```sh
+    echo 'security.authorization: enabled' >> /etc/mongod.conf
+    ```
+
+    Restart MongoDB: (the exact command will depend on your system and how you
+    installed it)
+
+    ```sh
+    sudo systemctl restart mongod
+    ```
+
+You can now connect as the `my-admin-user` user:
 
 ```sh
-DB_URL="mongodb://localhost:27017/refacto?ssl=true" ./index.js
+mongosh --authenticationDatabase admin -u my-admin-user -p
 ```
 
-Note that after enabling this, unless you also configure identity checks, you
-will need to skip certificate validation when connecting via the commandline:
+And configure Refacto to connect as the `my-refacto-user` user:
 
 ```sh
-mongo --ssl --sslAllowInvalidCertificates
+DB_URL="mongodb://my-refacto-user:<pass>@localhost:27017/my-refacto-db" ./index.js
 ```
 
-### Client / server identity checks
+<https://docs.mongodb.com/manual/tutorial/enable-authentication/>
 
-If the database is running on a separate server, you should enable client &
-server identity checks. The following resources offer guidance:
+### Encrypted communication
 
-- <https://docs.mongodb.com/manual/tutorial/configure-ssl/>
-- <https://medium.com/@rajanmaharjan/secure-your-mongodb-connections-ssl-tls-92e2addb3c89>
+If the database is running on a separate server, you should enable encrypted
+communication (to avoid eavesdropping) as well as client and server identity
+checks (to avoid man-in-the-middle attacks). See the
+[MongoDB documentation for guidance](https://www.mongodb.com/docs/manual/tutorial/configure-ssl/).
 
 ## Analytics / Diagnostics
 

docs/SERVICES.md

@@ -42,8 +42,8 @@ The configuration file will be created at `/usr/local/etc/mongod.conf` on macOS
 and `/etc/mongod.conf` on Ubuntu.
 
 _Note: MongoDB's default security model is enough for local development, but you
-should lock it down further in deployments. See the
-[security documentation](./SECURITY.md) for details._
+should lock it down further in deployments. See [SECURITY.md](./SECURITY.md) for
+details._
 
 ### Redis
 
@@ -265,7 +265,8 @@ line containing a JSON-encoded object of the form:
 ```
 
 When analytics are enabled, client-related log entries will also contain browser
-and OS versions (see the [security documentation](./SECURITY.md)).
+and OS versions (see the configuration options in
+[SECURITY.md](./SECURITY.md#analytics--diagnostics)).
 
 #### Log rotation