From ada8c164fec754bd552ec256f877a54e2d835405 Mon Sep 17 00:00:00 2001 From: Jonas Hendrickx Date: Tue, 3 Sep 2024 08:02:08 +0200 Subject: [PATCH] PAS-452 | Matching documentation for e-mail provider fallback (#146) --- src/guide/self-hosting/configuration.md | 191 +++++++++++++++++++----- 1 file changed, 152 insertions(+), 39 deletions(-) diff --git a/src/guide/self-hosting/configuration.md b/src/guide/self-hosting/configuration.md index 154883b0..2fc66c77 100644 --- 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,6 +63,8 @@ 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). ::: @@ -70,78 +72,189 @@ Read the 'WebAuthn' specification here: [See specification](https://www.w3.org/T 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": "", + "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) + + +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: -* 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='' +-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`. -```