PAS-452 | Matching documentation for e-mail provider fallback (#146)

Jonas Hendrickx · web-flow · commit ada8c164fec7 · 2024-09-03T08:02:08.000+02:00
diff --git a/src/guide/self-hosting/configuration.md b/src/guide/self-hosting/configuration.md
@@ -50,7 +50,7 @@ By default, the container will use Sqlite if nothing else is specified. The data
 | Key                   | Default   | Required | Description                                                                                                                                           |
 | --------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | BWP_ENABLE_SSL        | false     | N        | [true/false] See warning below.                                                                                                                       |
-| BWP_PORT              | 5701      | Y        | [0-65536] This will determine the port your self-hosted instance will be accessible from.                                                             |
+| BWP_PORT              | 5701      | N        | [0-65536] Only required if you don't use a reverse proxy.                                                                                             |
 | BWP_DOMAIN            | localhost | N        | [example.com] This will be the domain your self-hosted instance will be accessible from. It is important it matches for everything to work correctly. |
 | BWP_DB_PROVIDER       |           | N        | [mssql/sqlserver/] Defaults to using Sqlite if not set                                                                                                |
 | BWP_DB_SERVER         |           | N        | For any non-file hosted database, enter its domain name. Required for Microsoft SQL Server.                                                           |
@@ -63,85 +63,198 @@ By default, the container will use Sqlite if nothing else is specified. The data
 :::warning
 Setting SSL with `BWP_ENABLE_SSL` is required in [insecure contexts](https://w3c.github.io/webappsec-secure-contexts/#secure-contexts). Running the container locally on 'localhost' is considered a secure context.
 
+If you are using a load balancer or reverse proxy, you can leave it set to false and handle SSL termination there.
+
 Read the 'WebAuthn' specification here: [See specification](https://www.w3.org/TR/webauthn-2/#web-authentication-api).
 :::
 
 ## E-mail
 
 Email is used by Passwordless Admin Console to notify administrators of changes to their organization. This is specifically useful for verifying administrators when first signing up.
 
-By default, all e-mail communication is written to a file for each application.
-
-- `/app/Admin/mail.md`
-- `/app/Api/mail.md`
+By default, all e-mail communication is written to a file:
 
-When using the default configuration, the following commands will output the contents of each file.
+- `/app/mail.md`
 
-For Admin Console:
+When using the default configuration, the following command will output the contents of the file.
 
 ```bash
-docker exec -it {name-of-container} cat /app/AdminConsole/mail.md
+docker exec -it {name-of-container} cat /app/mail.md
+```
+
+### JSON
+
+Reference: [Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-8.0)
+
+What is important is to configure ‘Mail.From' as shown below. This is required to have a fallback e-mail address to send e-mails from. On the 'Mail.Providers’ is an array, which is an ordered list of e-mail providers that we will attempt to execute in order if they fail. To configure an e-mail provider, see the sub sections below.
+
+```json
+"Mail": {
+  "From": "johndoe@example.com",
+  "Providers": [
+    {
+      // Provider 1
+    },
+    {
+      // Provider 2
+    },
+    {
+      ...
+    }
+  ]
+},
+```
+
+#### AWS
+
+```json
+{
+  "Name": "aws",
+  "AccessKey": "aws_access_key_id",
+  "SecretKey": "aws_secret_key",
+  "Region": "us-west-2"
+}
+```
+
+#### File
+
+```json
+{
+  "Name": "file",
+  "Path": "/path/on/your/machine" //(optional)
+}
 ```
 
-For Api:
+#### SendGrid
+
+```json
+{
+  "Name": "sendgrid",
+  "ApiKey": "sendgrid_api_key"
+}
+```
+
+#### SMTP
+
+```json
+{
+  "Name": "smtp",
+  "Host": "smtp.example.com",
+  "Port": 123,
+  "Username": "johndoe",
+  "Password": "YourPassword123!",
+  "StartTls": true/false,
+  "Ssl": true/false,
+  "SslOverride": true/false,
+  "TrustServer": true/false // skips SSL certificate validation when set to `true`.
+}
+```
+
+Example with SendGrid:
+
+```json
+{
+  "Name": "smtp",
+  "Host": "smtp.sendgrid.net",
+  "Port": 465,
+  "Username": "apikey",
+  "Password": "<your-sendgrid-api-key>",
+  "StartTls": false,
+  "Ssl": true,
+  "SslOverride": false,
+  "TrustServer": true
+}
+```
+
+### Environment variables
+
+Reference: [Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-8.0)
+
+<!-- prettier-ignore -->
+What is important is to configure ‘Mail__From' as shown below. This is required to have a fallback e-mail address to send e-mails from. On the 'Mail__Providers’ is an array, which is an ordered list of e-mail providers that we will attempt to execute in order if they fail. To configure an e-mail provider, see the sub sections below.
+
+Arrays start at zero so we configure AWS to be the first in line to attempt to send e-mails from, if that fails, we fall back to SendGrid.
 
 ```bash
-docker exec -it {name-of-container} cat /app/Api/mail.md
+-e Mail__From='johndoe@example.com'
+-e Mail__FromName='John Doe'
+-e Mail__Providers__0__Name='aws'
+-e Mail__Providers__0__AccessKey='aws_access_key_id'
+-e Mail__Providers__0__SecretKey='aws_secret_key'
+-e Mail__Providers__1__Name='sendgrid'
+-e Mail__Providers__1__ApiKey='sendgrid_api_key'
 ```
 
-If you provide a directory for the application configuration to be stored in on your machine, the `mail.md` file will be located there.
+In the vendor specific examples below, we will always use '#' as the provider index.
 
-It's recommended you configure the SMTP parameters below:
+#### AWS
 
-| Key                  | Default | Required | Description                                                                             |
-| -------------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
-| BWP_SMTP_FROM        |         | Y        | Use your sender e-mail.                                                                 |
-| BWP_SMTP_USERNAME    |         | Y        |                                                                                         |
-| BWP_SMTP_PASSWORD    |         | Y        |                                                                                         |
-| BWP_SMTP_HOST        |         | Y        | Hostname                                                                                |
-| BWP_SMTP_PORT        |         | Y        | [0-65535]                                                                               |
-| BWP_SMTP_STARTTLS    | false   | N        | [true/false]                                                                            |
-| BWP_SMTP_SSL         | false   | N        | [true/false]                                                                            |
-| BWP_SMTP_TRUSTSERVER | false   | N        | [true/false] Allows you to skip certificate validation. Not recommended for production. |
+```bash
+-e Mail__Providers__#__Name='aws'
+-e Mail__Providers__#__AccessKey='aws_access_key_id'
+-e Mail__Providers__#__SecretKey='aws_secret_key'
+-e Mail__Providers__#__Region='us-west-2'
+```
 
-:::warning
-To verify e-mailing is working correctly:
+#### File
 
-- Create an admin with a new organization.
-- Invite an admin to an existing organization.
-  :::
+```bash
+-e Mail__Providers__#__Name='file'
+-e Mail__Providers__#__Path='/path/on/your/machine' #(optional)
+```
 
-### SendGrid example with SSL
+#### SendGrid
 
-For verifying e-mailing is working correctly, you can use health-checks, read more [here](health-checks).
+```bash
+-e Mail__Providers__#__Name='sendgrid'
+-e Mail__Providers__#__ApiKey='sendgrid_api_key'
+```
+
+#### SMTP
 
 ```bash
+-e Mail__Providers__#__Name='smtp'
+-e Mail__Providers__#__Host='smtp.example.com'
+-e Mail__Providers__#__Port=123
+-e Mail__Providers__#__Username='johndoe'
+-e Mail__Providers__#__Password='YourPassword123!'
+-e Mail__Providers__#__StartTls=true/false
+-e Mail__Providers__#__Ssl=true/false
+-e Mail__Providers__#__SslOverride=true/false
+-e Mail__Providers__#__TrustServer=true/false # skips SSL certificate validation when set to `true`.
+```
 
-* BWP_SMTP_FROM: you@example.com
-* BWP_SMTP_USERNAME: apikey
-* BWP_SMTP_PASSWORD: <your-api-key>
-* BWP_SMTP_HOST: smtp.sendgrid.net
-* BWP_SMTP_PORT: 465
-* BWP_SMTP_SSL: true
-* BWP_SMTP_TRUSTSERVER: true (for local testing)
+Example with SendGrid:
+
+```bash
+-e Mail__Providers__#__Name='smtp'
+-e Mail__Providers__#__Host='smtp.sendgrid.net'
+-e Mail__Providers__#__Port=465
+-e Mail__Providers__#__Username='apikey'
+-e Mail__Providers__#__Password='<your-sendgrid-api-key>'
+-e Mail__Providers__#__StartTls=false
+-e Mail__Providers__#__Ssl=true
+-e Mail__Providers__#__SslOverride=false
+-e Mail__Providers__#__TrustServer=true
+```
 
 ## config.json
 
 :::warning
 Requirements:
+
 - Persistent storage, see 'Volumes'.
-:::
+  :::
 
 `/etc/bitwarden_passwordless/config.json` is only generated when you have not specified the following environment variables:
 
-
 If you mount `/etc/bitwarden_passwordless` to your host. You can specify a `config.json`.
 
 If the following keys do not exist, they will be generated automatically:
+
 - Passwordless::ApiKey
 - Passwordless::ApiSecret
 - PasswordlessManagement::ManagementKey
 - SALT_KEY
 
 It is recommended that you have them generated automatically, the first time you run `bitwarden/passwordless-self-host`.
-```
