From b1d59dcec429a97ccbb106882c141528be260a2c Mon Sep 17 00:00:00 2001 From: Clement Michaud Date: Mon, 28 Oct 2019 23:41:21 +0100 Subject: [PATCH] Add documentation on Authelia v4 in README and add a migration document. --- AUTHELIA-V4.md | 38 ++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 8 ++++++++ README.md | 5 +++++ config.template.yml | 2 +- 4 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 AUTHELIA-V4.md diff --git a/AUTHELIA-V4.md b/AUTHELIA-V4.md new file mode 100644 index 000000000..a0ad4e784 --- /dev/null +++ b/AUTHELIA-V4.md @@ -0,0 +1,38 @@ +# Authelia v4 + +Authelia has been rewritten in Go for better code maintainability and for performance and security reasons. + +The principles stay the same, Authelia is still an authenticating and authorizing proxy. Some major changes have been made though so +that the system is more reliable overall. + +Majors changes: +* The configuration mostly remained the same, only one major key has been added: `jwt_secret` and one key removed: `secure` from the +SMTP notifier as the Go SMTP library default to TLS if available. +* The local storage previously used as a replacement of mongo for dev purpose was a `nedb` database which was implementing the same interface +as mongo but was not really standard. It has been replaced by a good old sqlite3 database. +* The model of the database is not compatible with v3. This has been decided to better fit with Golang libraries. +* Some features have been upgraded such as U2F in order to use the latest security features available like allowing device cloning detection. +* Furthermore, a top-notch web server implementation (fasthttp) has been selected to allow a large performance gain in order to use Authelia in demanding environments. + + +## Migration from v3 to v4 + +Please note that the migration is breaking the configuration and the data model. Therefore the actions proposed (as of now) to do the migration will make you lose previously registered devices that you'll need to register again in v4. + +### Automatic Steps + +Since v4 is in beta phase, manual steps are provided for those who are ready to lose their configuration or bootstrap a new instance. +However a migration script will be provided later on. Help for writing this script will be welcome by the way. + +### Manual Steps + +* Add the `jwt_secret` key in the configuration along with the value of the secret. This secret is used to generate expirable JWT tokens +for operations requiring identity validation. +* Remove the `secure` key of your SMTP notifier configuration as the Go implementation of the SMTP library uses TLS by default if available. + +#### If using the local storage +* Remove the directory of the storage (beware you will lose your previous configuration: U2F, TOTP devices). Replace the path with a path to a sqlite3 database, +it is the new standard way of storing data in Authelia. + +#### If using the mongo storage +* Flush your collections (beware you will lose your previous configuration: U2F, TOTP devices). New collections will be created by Authelia. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c9d384d2..107b0f958 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,11 @@ +Release Notes - Version 4.0.0 +------------------------------ +* Authelia is rewritten in Go. +* config.yml should include a secret for jwt issuance and verification. +* Models in database have been updated to better fit with the Go library. +* The local storage has been replaced by a good old sqlite3 database. +* The "secure" flag from the SMTP notifier configuration has been removed as TLS is used by default when available. + Release Notes - Version 3.16.3 ------------------------------ * Update changelog of previous versions. diff --git a/README.md b/README.md index b6c1ec45e..e91d1c069 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,11 @@ providing 2-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion of reverse proxies like [nginx] or [Traefik] by handling forwarded authentication and authorization requests. + BREAKING NEWS: Authelia v4 is here! The new version is written in Go for reliability, performance and security improvements. + It is currently available in beta. + Please read AUTHELIA-V4.md if you want to migrate from v3 to v4. But note that the data model migration is not automated yet. + +

diff --git a/config.template.yml b/config.template.yml index e2c9b5c24..4301f577a 100644 --- a/config.template.yml +++ b/config.template.yml @@ -247,7 +247,7 @@ regulation: storage: # The directory where the DB files will be saved ## local: - ## path: /var/lib/authelia/store + ## path: /var/lib/authelia/db.sqlite3 # Settings to connect to mongo server mongo: