Skip to content

Commit

Permalink
PAS-452 | Matching documentation for e-mail provider fallback (#146)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jonashendrickx
jonashendrickx authored Sep 3, 2024
1 parent da3d337 commit ada8c16
Showing 1 changed file with 152 additions and 39 deletions.
191 changes: 152 additions & 39 deletions src/guide/self-hosting/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -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": "[email protected]",
"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='[email protected]'
-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: [email protected]
* 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`.
```

0 comments on commit ada8c16

Please sign in to comment.