techies/authelia
1
0
Fork 0
mirror of https://github.com/0rangebananaspy/authelia.git synced 2024-09-14 22:47:21 +07:00
Code Issues Projects Releases Wiki Activity

Update documentation to introduce migration scripts.

Browse Source
This commit is contained in:
Clement Michaud 2019-11-17 16:31:27 +01:00 committed by Clément Michaud
parent 3b2d733367
commit eafd9330dc
5 changed files with 43 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
AUTHELIA-V4.md
View File

@ -1,40 +0,0 @@
# 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 used 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.
* Make sure users and groups filter in the LDAP configuration have outer parenthesis. The standard format of LDAP filters always include outer
parenthesis. You can find some examples in the "Examples" section of the following document: https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx
#### If you were 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 you were using the mongo storage
* Flush your collections (beware you will lose your previous configuration: U2F, TOTP devices). New collections will be created by Authelia.

42
BREAKING.md
View File

@ -2,19 +2,49 @@ Breaking changes
================ ================
Since Authelia is still under active development, it is subject to breaking changes. We then recommend you don't blindly use the latest Since Authelia is still under active development, it is subject to breaking changes. We then recommend you don't blindly use the latest
Docker image but pick a version instead and check this file before upgrading. This is where you will get information about breaking changes and about what you should do to overcome those changes. Docker image but pick a version instead and read this documentation before upgrading. This is where you will get information about breaking
changes and about what you should do to overcome those changes.
## Breaking in v4.0.0 ## Breaking in v4.0.0
Authelia has been rewritten in Go for better performance and reliability. Authelia has been rewritten in Go for better code maintainability and for performance and security reasons.
### Model of U2F devices 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. This induced breaking the previous data model and the configuration to bring new features
but fortunately migration tools are provided to ease the task.
The model of U2F devices has been updated to better fit with the Go library handling U2F keys. ### Migration tools
### Removal of flag secure for SMTP notifier An authelia-scripts command is provided to perform the data model migration from a local database
or a mongo database created by Authelia v3 into a target SQL database (sqlite3, mysql, postgres)
supported by Authelia v4.
The go library for sending e-mails automatically switch to TLS if possible according to https://golang.org/pkg/net/smtp/#SendMail. Example of usage:
# Migrate a local database into the targeted database defined in config-v4.yml
authelia-scripts migrate local --config=/path/to/config-v4.yml --db-path=/old/db/path
# Migrate a mongo database into the targeted database defined in config-v4.yml
authelia-scripts migrate mongo --config=/path/to/config-v4.yml --url=mongodb://myuser:mypassword@mymongo:27017 --database=authelia
Those commands migrate TOTP secrets, U2F devices, authentication traces and user preferences so
that the migration is almost seamless for your users.
The identity verification tokens are not migrated though since their format has changed. However they were
made to expire after a few minutes anyway. Consequently, the users who initiated a device registration process
which has not been completed before the migration will have to restart the device registration process for their
device. This is because their identity verification token will not be usable in v4.
### Major changes in details:
* 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 used 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.
## Breaking in v3.14.0 ## Breaking in v3.14.0

6
CHANGELOG.md
View File

@ -4,9 +4,13 @@ Release Notes - Version 4.0.0
* config.yml should include a secret for jwt issuance and verification. * config.yml should include a secret for jwt issuance and verification.
* Models in database have been updated to better fit with the Go library. * 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 local storage has been replaced by a good old sqlite3 database.
* The mongo option for storing user preferences and device secrets has been deprecated in favor of SQL options: mysql and postgres.
* The "secure" flag from the SMTP notifier configuration has been removed as TLS is used by default when available. * The "secure" flag from the SMTP notifier configuration has been removed as TLS is used by default when available.
* authelia-scripts tool has been rewritten in Go. * authelia-scripts tool has been rewritten in Go.
* Use pure implementation of crypt to avoid CGO and dependency to libc. * Use pure implementation of crypt.
* Introduction of a "migrate" command to authelia-scripts to help migrating from v3 to v4.
* Authelia is built and available on Dockerhub in 3 flavors: amd64, arm32v7 and arm64v8.
* Introduction of suites in Go.
Release Notes - Version 3.16.3 Release Notes - Version 3.16.3
------------------------------ ------------------------------

2
README.md
View File

@ -14,7 +14,7 @@ It acts as a companion of reverse proxies like [nginx] or [Traefik] by handling
BREAKING NEWS: Authelia v4 release is coming soon! The new version is written in Go for reliability, performance and security improvements. BREAKING NEWS: Authelia v4 release is coming soon! The new version is written in Go for reliability, performance and security improvements.
It is currently available in beta in master. It is currently available in beta in master.
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. Please read BREAKING.md if you want to migrate from v3 to v4. Otherwise, start fresh in v4 and enjoy!
<p align="center"> <p align="center">

1
cmd/authelia-scripts/cmd_bootstrap.go
View File

@ -224,6 +224,7 @@ func Bootstrap(cobraCmd *cobra.Command, args []string) {
bootstrapPrintln("Preparing /etc/hosts to serve subdomains of example.com...") bootstrapPrintln("Preparing /etc/hosts to serve subdomains of example.com...")
prepareHostsFile() prepareHostsFile()
fmt.Println()
bootstrapPrintln("Run 'authelia-scripts suites setup Standalone' to start Authelia and visit https://home.example.com:8080.") bootstrapPrintln("Run 'authelia-scripts suites setup Standalone' to start Authelia and visit https://home.example.com:8080.")
bootstrapPrintln("More details at https://github.com/clems4ever/authelia/blob/master/docs/getting-started.md") bootstrapPrintln("More details at https://github.com/clems4ever/authelia/blob/master/docs/getting-started.md")
} }