diff options
Diffstat (limited to 'docs/content/en/configuration/storage')
| -rw-r--r-- | docs/content/en/configuration/storage/_index.md | 9 | ||||
| -rw-r--r-- | docs/content/en/configuration/storage/introduction.md | 60 | ||||
| -rw-r--r-- | docs/content/en/configuration/storage/migrations.md | 36 | ||||
| -rw-r--r-- | docs/content/en/configuration/storage/mysql.md | 100 | ||||
| -rw-r--r-- | docs/content/en/configuration/storage/postgres.md | 139 | ||||
| -rw-r--r-- | docs/content/en/configuration/storage/sqlite.md | 44 |
6 files changed, 388 insertions, 0 deletions
diff --git a/docs/content/en/configuration/storage/_index.md b/docs/content/en/configuration/storage/_index.md new file mode 100644 index 000000000..60f7cca21 --- /dev/null +++ b/docs/content/en/configuration/storage/_index.md @@ -0,0 +1,9 @@ +--- +title: "Storage" +description: "Storage Configuration" +lead: "" +date: 2022-03-20T12:52:27+11:00 +draft: false +images: [] +weight: 106000 +--- diff --git a/docs/content/en/configuration/storage/introduction.md b/docs/content/en/configuration/storage/introduction.md new file mode 100644 index 000000000..0d565c539 --- /dev/null +++ b/docs/content/en/configuration/storage/introduction.md @@ -0,0 +1,60 @@ +--- +title: "Storage" +description: "Storage Configuration" +lead: "Configuring the SQL Storage." +date: 2022-03-20T12:52:27+11:00 +draft: false +images: [] +menu: + configuration: + parent: "storage" +weight: 106100 +toc: true +aliases: + - /docs/configuration/storage/ +--- + +__Authelia__ supports multiple storage backends. The backend is used to store user preferences, 2FA device handles and +secrets, authentication logs, etc... + +The available storage backends are listed in the table of contents below. + +## Configuration + +```yaml +storage: + encryption_key: a_very_important_secret + local: {} + mysql: {} + postgres: {} +``` + +## Options + +### encryption_key + +{{< confkey type="string" required="yes" >}} + +The encryption key used to encrypt data in the database. We encrypt data by creating a sha256 checksum of the provided +value, and use that to encrypt the data with the AES-GCM 256bit algorithm. + +The minimum length of this key is 20 characters, however we generally recommend above 64 characters. + +This secret must be generated by the administrator and can +be done by following the +[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) +guide. + +See [securty measures](../../overview/security/measures.md#storage-security-measures) for more information. + +### postgres + +See [PostgreSQL](postgres.md). + +### local + +See [SQLite](sqlite.md). + +### mysql + +See [MySQL](mysql.md). diff --git a/docs/content/en/configuration/storage/migrations.md b/docs/content/en/configuration/storage/migrations.md new file mode 100644 index 000000000..b2a77512f --- /dev/null +++ b/docs/content/en/configuration/storage/migrations.md @@ -0,0 +1,36 @@ +--- +title: "Migrations" +description: "Storage Migrations" +lead: "A migration ." +date: 2022-03-20T12:52:27+11:00 +draft: false +images: [] +menu: + configuration: + parent: "storage" +weight: 106200 +toc: true +aliases: + - /docs/configuration/storage/migrations.html +--- + +Storage migrations are important for keeping your database compatible with Authelia. Authelia will automatically upgrade +your schema on startup. However, if you wish to use an older version of Authelia you may be required to manually +downgrade your schema with a version of Authelia that supports your current schema. + +## Schema Version to Authelia Version map + +This table contains a list of schema versions and the corresponding release of Authelia that shipped with that version. +This means all Authelia versions between two schema versions use the first schema version. + +For example for version pre1, it is used for all versions between it and the version 1 schema, so 4.0.0 to 4.32.2. In +this instance if you wanted to downgrade to pre1 you would need to use an Authelia binary with version 4.33.0 or higher. + +| Schema Version | Authelia Version | Notes | +|:--------------:|:----------------:|:--------------------------------------------------------------------------------------------------:| +| pre1 | 4.0.0 | Downgrading to this version requires you use the --pre1 flag | +| 1 | 4.33.0 | Initial migration managed version | +| 2 | 4.34.0 | WebAuthn - added webauthn_devices table, altered totp_config to include device created/used dates | +| 3 | 4.34.2 | WebAuthn - fix V2 migration kid column length and provide migration path for anyone on V2 | +| 4 | 4.35.0 | Added OpenID Connect storage tables and opaque user identifier tables | +| 5 | 4.35.1 | Fixed the oauth2_consent_session table to accept NULL subjects for users who are not yet signed in | diff --git a/docs/content/en/configuration/storage/mysql.md b/docs/content/en/configuration/storage/mysql.md new file mode 100644 index 000000000..6b0ffb827 --- /dev/null +++ b/docs/content/en/configuration/storage/mysql.md @@ -0,0 +1,100 @@ +--- +title: "MySQL" +description: "MySQL Configuration" +lead: "The MySQL storage provider which supports both MySQL and MariaDB." +date: 2022-03-20T12:52:27+11:00 +draft: false +images: [] +menu: + configuration: + parent: "storage" +weight: 106600 +toc: true +aliases: + - /docs/configuration/storage/mariadb.html + - /docs/configuration/storage/mysql.html +--- + +## Version support + +When using MySQL or MariaDB we recommend using the latest version that is officially supported by the MySQL or MariaDB +developers. We also suggest checking out [PostgreSQL](postgres.md) as an alternative. + +The oldest versions that have been tested are MySQL 5.7 and MariaDB 10.6. + +If using MySQL 5.7 or MariaDB 10.6 you may be required to adjust the `explicit_defaults_for_timestamp` setting. This +will be evident when the container starts with an error similar to `Error 1067: Invalid default value for 'exp'`. You +can adjust this setting in the mysql.cnf file like so: + +```cnf +[mysqld] +explicit_defaults_for_timestamp = 1 +``` + +## Configuration + +```yaml +storage: + encryption_key: a_very_important_secret + mysql: + host: 127.0.0.1 + port: 3306 + database: authelia + username: authelia + password: mypassword + timeout: 5s +``` + +## Options + +### encryption_key + +See the [encryption_key docs](introduction.md#encryption_key). + +### host + +{{< confkey type="string" default="localhost" required="no" >}} + +The database server host. + +If utilising an IPv6 literal address it must be enclosed by square brackets and quoted: + +```yaml +host: "[fd00:1111:2222:3333::1]" +``` + +### port + +{{< confkey type="integer" default="3306" required="no" >}} + +The port the database server is listening on. + +### database + +{{< confkey type="string" required="yes" >}} + +The database name on the database server that the assigned [user](#username) has access to for the purpose of +__Authelia__. + +### username + +{{< confkey type="string" required="yes" >}} + +The username paired with the password used to connect to the database. + +### password + +{{< confkey type="string" required="yes" >}} + +The password paired with the username used to connect to the database. Can also be defined using a +[secret](../methods/secrets.md) which is also the recommended way when running as a container. + +We recommend generating a random string with 64 characters or more for this purposes which can be done by following the +[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) +guide. + +### timeout + +{{< confkey type="duration" default="5s" required="no" >}} + +The SQL connection timeout. diff --git a/docs/content/en/configuration/storage/postgres.md b/docs/content/en/configuration/storage/postgres.md new file mode 100644 index 000000000..2dd22859a --- /dev/null +++ b/docs/content/en/configuration/storage/postgres.md @@ -0,0 +1,139 @@ +--- +title: "PostgreSQL" +description: "PostgreSQL Configuration" +lead: "The PostgreSQL storage provider." +date: 2022-03-20T12:52:27+11:00 +draft: false +images: [] +menu: + configuration: + parent: "storage" +weight: 106400 +toc: true +aliases: + - /docs/configuration/storage/postgres.html +--- + +## Version support + +See [PostgreSQL support](https://www.postgresql.org/support/versioning/) for the versions supported by PostgreSQL. We +recommend the *current minor* version of one of the versions supported by PostgreSQL. + +The versions of PostgreSQL that should be supported by Authelia are: + +* 14 +* 13 +* 12 +* 11 +* 10 +* 9.6 + +## Configuration + +```yaml +storage: + encryption_key: a_very_important_secret + postgres: + host: 127.0.0.1 + port: 5432 + database: authelia + schema: public + username: authelia + password: mypassword + ssl: + mode: disable + root_certificate: /path/to/root_cert.pem + certificate: /path/to/cert.pem + key: /path/to/key.pem +``` + +## Options + +### encryption_key + +See the [encryption_key docs](introduction.md#encryption_key). + +### host + +{{< confkey type="string" required="yes" >}} + +The database server host. + +If utilising an IPv6 literal address it must be enclosed by square brackets and quoted: + +```yaml +host: "[fd00:1111:2222:3333::1]" +``` + +### port + +{{< confkey type="integer" default="5432" required="no" >}} + +The port the database server is listening on. + +### database + +{{< confkey type="string" required="yes" >}} + +The database name on the database server that the assigned [user](#username) has access to for the purpose of +__Authelia__. + +### schema + +{{< confkey type="string" default="public" required="no" >}} + +The database schema name to use on the database server that the assigned [user](#username) has access to for the purpose +of __Authelia__. By default this is the public schema. + +### username + +{{< confkey type="string" required="yes" >}} + +The username paired with the password used to connect to the database. + +### password + +{{< confkey type="string" required="yes" >}} + +The password paired with the username used to connect to the database. Can also be defined using a +[secret](../methods/secrets.md) which is also the recommended way when running as a container. + +We recommend generating a random string with 64 characters or more for this purposes which can be done by following the +[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) +guide. + +### timeout + +{{< confkey type="duration" default="5s" required="no" >}} + +The SQL connection timeout. + +### ssl + +#### mode + +{{< confkey type="string" default="disable" required="no" >}} + +SSL mode configures how to handle SSL connections with Postgres. +Valid options are 'disable', 'require', 'verify-ca', or 'verify-full'. +See the [PostgreSQL Documentation](https://www.postgresql.org/docs/12/libpq-ssl.html) +or [pgx - PostgreSQL Driver and Toolkit Documentation](https://pkg.go.dev/github.com/jackc/pgx?tab=doc) +for more information. + +#### root_certificate + +{{< confkey type="string" required="no" >}} + +The optional location of the root certificate file encoded in the PEM format for validation purposes. + +#### certificate + +{{< confkey type="string" required="no" >}} + +The optional location of the certificate file encoded in the PEM format for validation purposes. + +#### key + +{{< confkey type="string" required="no" >}} + +The optional location of the key file encoded in the PEM format for authentication purposes. diff --git a/docs/content/en/configuration/storage/sqlite.md b/docs/content/en/configuration/storage/sqlite.md new file mode 100644 index 000000000..9e54ee04a --- /dev/null +++ b/docs/content/en/configuration/storage/sqlite.md @@ -0,0 +1,44 @@ +--- +title: "SQLite3" +description: "SQLite3 Configuration" +lead: "The SQLite3 storage provider." +date: 2022-03-20T12:52:27+11:00 +draft: false +images: [] +menu: + configuration: + parent: "storage" +weight: 106500 +toc: true +aliases: + - /docs/configuration/storage/sqlite.html +--- + +If you don't have a SQL server, you can use [SQLite](https://en.wikipedia.org/wiki/SQLite). +However please note that this setup will prevent you from running multiple +instances of Authelia since the database will be a local file. + +Use of this storage provider leaves Authelia [stateful](../../overview/authorization/statelessness.md). It's important +in highly available scenarios to use one of the other providers, and we highly recommend it in production environments, +but this requires you setup an external database such as [PostgreSQL](postgres.md). + +## Configuration + +```yaml +storage: + encryption_key: a_very_important_secret + local: + path: /config/db.sqlite3 +``` + +## Options + +### encryption_key + +See the [encryption_key docs](introduction.md#encryption_key). + +### path + +{{< confkey type="string" required="yes" >}} + +The path where the SQLite3 database file will be stored. It will be created if the file does not exist. |