diff --git a/README.md b/README.md
index c1d192b8..6e68b0c0 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
- 
+ 
[][Apache 2.0]
@@ -16,25 +16,25 @@ It acts as a companion of reverse proxies like [nginx] or [Traefik] by handling
- 
- 
- 
- 
+ 
+ 
+ 
+ 
**Authelia** can be installed as a standalone service using Docker or NPM
but can also be deployed easily on [Kubernetes] leveraging ingress controllers and ingress configuration.
- 
- 
+ 
+ 
Here is what Authelia's portal looks like
- 
- 
+ 
+ 
## Features summary
@@ -42,9 +42,9 @@ Here is what Authelia's portal looks like
Here is the list of the main available features:
* Several kind of second factor:
- * **[Security Key (U2F)](https://github.com/clems4ever/authelia/blob/master/docs/2factor/security-key.md)** with [Yubikey].
- * **[Time-based One-Time password](https://github.com/clems4ever/authelia/blob/master/docs/2factor/time-based-one-time-password.md)** with [Google Authenticator].
- * **[Mobile Push Notifications](https://github.com/clems4ever/authelia/blob/master/docs/2factor/duo-push-notifications.md)** with [Duo](https://duo.com/).
+ * **[Security Key (U2F)](./docs/2factor/security-key.md)** with [Yubikey].
+ * **[Time-based One-Time password](./docs/2factor/time-based-one-time-password.md)** with [Google Authenticator].
+ * **[Mobile Push Notifications](./docs/2factor/duo-push-notifications.md)** with [Duo](https://duo.com/).
* Password reset with identity verification using email confirmation.
* Single-factor only authentication method available.
* Access restriction after too many authentication attempts.
@@ -53,7 +53,7 @@ Here is the list of the main available features:
* Highly-available using distributed database and KV store.
* Compatible with Kubernetes [ingress-nginx](https://github.com/kubernetes/ingress-nginx) controller out of the box.
-For more details about the features, follow [Features](https://github.com/clems4ever/authelia/blob/master/docs/features.md).
+For more details about the features, follow [Features](./docs/features.md).
## Proxy support
@@ -62,9 +62,9 @@ Authelia works in combination with [nginx] or [Traefik] and soon with [HAProxy]
Docker or directly in [Kubernetes].
-
-
-
+
+
+
## Getting Started
@@ -74,12 +74,12 @@ You can start off with
git clone https://github.com/clems4ever/authelia.git && cd authelia
source bootstrap.sh
-If you want to go further, please read [Getting Started](https://github.com/clems4ever/authelia/blob/master/docs/getting-started.md).
+If you want to go further, please read [Getting Started](./docs/getting-started.md).
## Deployment
Now that you have tested **Authelia** and you want to try it out in your own infrastructure,
-you can learn how to deploy and use it with [Deployment](https://github.com/clems4ever/authelia/blob/master/docs/deployment-production.md).
+you can learn how to deploy and use it with [Deployment](./docs/deployment-production.md).
This guide will show you how to deploy it on bare metal as well as on
[Kubernetes](https://kubernetes.io/).
@@ -87,11 +87,11 @@ This guide will show you how to deploy it on bare metal as well as on
If you want more information about the security measures applied by
**Authelia** and some tips on how to set up **Authelia** in a secure way,
-refer to [Security](https://github.com/clems4ever/authelia/blob/master/docs/security.md).
+refer to [Security](./docs/security.md).
## Changelog & Breaking changes
-See [CHANGELOG.md](https://github.com/clems4ever/authelia/blob/master/CHANGELOG.md) and [BREAKING.md](https://github.com/clems4ever/authelia/blob/master/BREAKING.md).
+See [CHANGELOG.md](./CHANGELOG.md) and [BREAKING.md](./BREAKING.md).
## Contribute
@@ -104,12 +104,12 @@ I am very grateful to contributors for their contributions to the project. Don't
## Build Authelia
-If you want to contribute with code, you should follow the documentation explaining how to [build](https://github.com/clems4ever/authelia/blob/master/docs/build-and-dev.md) the application.
+If you want to contribute with code, you should follow the documentation explaining how to [build](./docs/build-and-dev.md) the application.
## License
**Authelia** is **licensed** under the **[Apache 2.0]** license. The terms of the license are detailed
-in [LICENSE](https://github.com/clems4ever/authelia/blob/master/LICENSE).
+in [LICENSE](./LICENSE).
[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
@@ -118,7 +118,7 @@ in [LICENSE](https://github.com/clems4ever/authelia/blob/master/LICENSE).
[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
[auth_request]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
-[config.template.yml]: https://github.com/clems4ever/authelia/blob/master/config.template.yml
+[config.template.yml]: ./config.template.yml
[nginx]: https://www.nginx.com/
[Traefik]: https://traefik.io/
[HAproxy]: http://www.haproxy.org/
diff --git a/README.replaced b/README.replaced
new file mode 100644
index 00000000..65e85456
--- /dev/null
+++ b/README.replaced
@@ -0,0 +1,125 @@
+
+ 
+
+
+ [][Apache 2.0]
+ [](https://travis-ci.org/clems4ever/authelia)
+ [](https://gitter.im/authelia/general?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
+
+**Authelia** is an open-source authentication and authorization server
+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 stable release is coming soon! The new version is written in Go for reliability, performance and security improvements. A docker image is currently available in alpha version on dockerhub.
+ Please read BREAKING.md if you want to migrate from v3 to v4. Otherwise, start fresh in v4 and enjoy!
+
+
+
+ 
+ 
+ 
+ 
+
+
+**Authelia** can be installed as a standalone service using Docker or NPM
+but can also be deployed easily on [Kubernetes] leveraging ingress controllers and ingress configuration.
+
+
+ 
+ 
+
+
+Here is what Authelia's portal looks like
+
+
+ 
+ 
+
+
+## Features summary
+
+Here is the list of the main available features:
+
+* Several kind of second factor:
+ * **[Security Key (U2F)](https://github.com/clems4ever/authelia/raw/master/docs/2factor/security-key.md)** with [Yubikey].
+ * **[Time-based One-Time password](https://github.com/clems4ever/authelia/raw/master/docs/2factor/time-based-one-time-password.md)** with [Google Authenticator].
+ * **[Mobile Push Notifications](https://github.com/clems4ever/authelia/raw/master/docs/2factor/duo-push-notifications.md)** with [Duo](https://duo.com/).
+* Password reset with identity verification using email confirmation.
+* Single-factor only authentication method available.
+* Access restriction after too many authentication attempts.
+* Fine-grained access control per subdomain, user, resource and network.
+* Support of basic authentication for endpoints protected by single factor.
+* Highly-available using distributed database and KV store.
+* Compatible with Kubernetes [ingress-nginx](https://github.com/kubernetes/ingress-nginx) controller out of the box.
+
+For more details about the features, follow [Features](https://github.com/clems4ever/authelia/raw/master/docs/features.md).
+
+## Proxy support
+
+Authelia works in combination with [nginx] or [Traefik] and soon with [HAProxy] as discussed in
+[#271](https://github.com/clems4ever/authelia/issues/271). It can be deployed on bare metal with
+Docker or directly in [Kubernetes].
+
+
+
+
+
+
+
+## Getting Started
+
+You can start off with
+
+ git clone https://github.com/clems4ever/authelia.git && cd authelia
+ source bootstrap.sh
+
+If you want to go further, please read [Getting Started](https://github.com/clems4ever/authelia/raw/master/docs/getting-started.md).
+
+## Deployment
+
+Now that you have tested **Authelia** and you want to try it out in your own infrastructure,
+you can learn how to deploy and use it with [Deployment](https://github.com/clems4ever/authelia/raw/master/docs/deployment-production.md).
+This guide will show you how to deploy it on bare metal as well as on
+[Kubernetes](https://kubernetes.io/).
+
+## Security
+
+If you want more information about the security measures applied by
+**Authelia** and some tips on how to set up **Authelia** in a secure way,
+refer to [Security](https://github.com/clems4ever/authelia/raw/master/docs/security.md).
+
+## Changelog & Breaking changes
+
+See [CHANGELOG.md](./CHANGELOG.md) and [BREAKING.md](./BREAKING.md).
+
+## Contribute
+
+Anybody willing to contribute to the project either with code,
+documentation, security reviews or whatever, are very welcome to issue
+or review pull requests and take part to discussions in
+[Gitter](https://gitter.im/authelia/general?utm_source=share-link&utm_medium=link&utm_campaign=share-link).
+
+I am very grateful to contributors for their contributions to the project. Don't hesitate, be the next!
+
+## Build Authelia
+
+If you want to contribute with code, you should follow the documentation explaining how to [build](https://github.com/clems4ever/authelia/raw/master/docs/build-and-dev.md) the application.
+
+## License
+
+**Authelia** is **licensed** under the **[Apache 2.0]** license. The terms of the license are detailed
+in [LICENSE](./LICENSE).
+
+
+[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
+[TOTP]: https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm
+[Security Key]: https://www.yubico.com/about/background/fido/
+[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
+[auth_request]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
+[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
+[config.template.yml]: ./config.template.yml
+[nginx]: https://www.nginx.com/
+[Traefik]: https://traefik.io/
+[HAproxy]: http://www.haproxy.org/
+[Kubernetes]: https://kubernetes.io/
diff --git a/cmd/authelia-scripts/docker.go b/cmd/authelia-scripts/docker.go
index f04e08f1..f38e155b 100644
--- a/cmd/authelia-scripts/docker.go
+++ b/cmd/authelia-scripts/docker.go
@@ -57,5 +57,5 @@ func (d *Docker) CleanTag(tag string) error {
// PublishReadme push README.md to dockerhub.
func (d *Docker) PublishReadme() error {
- return utils.CommandWithStdout("bash", "-c", `jq -n --arg msg "$(
- 
+ 
In order to use this feature, you should first create a free account on Duo
(up to 10 users), create a user account and attach it a mobile device. The name
-of the user must match the name of the user in your internal database.
-Then, click on *Applications* and *Protect an Application*. Then select the option
-called *Partner Auth API*. This will generate an integration key, a secret key and
-a hostname. You can set the name of the application to **Authelia** and then you
-must add the generated information to your configuration as:
+of the user must match the name of the user in your internal database (LDAP).
+In Duo interface, click on *Applications* and *Protect an Application*. Then
+select the option called *Partner Auth API*. This will generate an integration key,
+a secret key and a hostname. You can set the name of the application to
+**Authelia** and then you must add the generated information to your configuration
+as:
duo_api:
hostname: api-123456789.example.com
@@ -25,12 +26,12 @@ must add the generated information to your configuration as:
This can be seen in [config.template.yml](../../config.template.yml) file.
-When selecting *Duo Push Notification* at the second factor stage, you will
+When selecting *Push Notification* at the second factor stage, you will
automatically receive a push notification on your phone to grant or deny access.
- 
- 
+ 
+ 
## Limitations
@@ -41,7 +42,7 @@ Users must be enrolled via the Duo Admin panel, they cannot enroll a device from
## FAQ
-### Why don't I have access to the *Duo Push Notification* option?
+### Why don't I have access to the *Push Notification* option?
It's likely that you have not configured **Authelia** correctly. Please read this
documentation again and be sure you had a look at [config.template.yml](../../config.template.yml).
\ No newline at end of file
diff --git a/docs/2factor/security-key.md b/docs/2factor/security-key.md
index c1f748cf..aba3898b 100644
--- a/docs/2factor/security-key.md
+++ b/docs/2factor/security-key.md
@@ -1,30 +1,30 @@
# Security Keys (U2F)
-**Authelia** also offers authentication using Security Keys supporting U2F
-like [Yubikey](Yubikey) USB devices. U2F is one of the most secure
-authentication protocol and is already available for Google, Facebook, Github
-accounts and more.
+**Authelia** offers authentication using Security Keys like [Yubikey](Yubikey)
+which are one of the most secure way to authenticate and get authorized.
+It is already available for Google, Facebook, Github accounts and more.
-The protocol requires your security key being enrolled before authenticating.
+The protocol requires your security key to enrolled before authenticating.
-
- 
-
+To do so, select the *Security Key* method at the second factor stage and
+click on the link *Not registered yet?*. This will send a link to your
+user email address. This e-mail will likely be sent to
+https://mail.example.com:8080/ if you're testing Authelia and you've not
+configured anything.
-To do so, select the *Security Key* method in the second factor page and click
-on the *register new device* link. This will send a link to the
-user email address. This e-mail will likely be sent to https://mail.example.com:8080/
-if you're testing Authelia and you've not configured anything.
-
-Confirm your identity by clicking on **Continue** and you'll be asked to
+Confirm your identity by clicking on **Register** and you'll be asked to
touch the token of your security key to enroll.
- 
+ 
-Upon successful registration, you can authenticate using your security key by simply
-touching the token again.
+Upon successful registration, you can authenticate using your security key
+by simply touching the token again when required:
+
+
+ 
+
Easy, right?!
@@ -32,9 +32,9 @@ Easy, right?!
### Why don't I have access to the *Security Key* option?
-U2F protocol is a new protocol that is only supported by recent browser
-and must even be enabled on some of them like Firefox. Please be sure
-your browser supports U2F and that the feature is enabled to make the
-option available in **Authelia**.
+U2F protocol is a new protocol that is only supported by recent browsers
+and might even be enabled on some of them. Please be sure your browser
+supports U2F and that the feature is enabled to make the option
+available in **Authelia**.
[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
diff --git a/docs/2factor/time-based-one-time-password.md b/docs/2factor/time-based-one-time-password.md
index 2ef9bbf7..ee372ae3 100644
--- a/docs/2factor/time-based-one-time-password.md
+++ b/docs/2factor/time-based-one-time-password.md
@@ -4,25 +4,25 @@ In **Authelia**, your users can use [Google Authenticator] for generating unique
tokens that they can use to pass the second factor.
- 
+ 
-Select the *One-Time Password method* and click on the *register new device* link.
+Select the *One-Time Password method* and click on the *Not registered yet?* link.
Then, check the email sent by **Authelia** to your email address
to validate your identity. If you're testing **Authelia**, it's likely
that this e-mail has been sent to https://mail.example.com:8080/
-Confirm your identity by clicking on **Continue** and you'll get redirected
-on a page where your secret will be displayed as QRCode and in Base32 formats.
+Confirm your identity by clicking on **Register** and you'll get redirected
+on a page where your secret will be displayed as QRCode that you can scan.
- 
+ 
You can use [Google Authenticator] to store it.
-From now on, you'll get generated
-tokens from your phone that you can use to validate the second factor in **Authelia**.
+From now on, you'll get tokens generated every 30 seconds on your phone that
+you can use to validate the second factor in **Authelia**.
diff --git a/docs/authelia-scripts.md b/docs/authelia-scripts.md
index 14fc2b12..75de7c71 100644
--- a/docs/authelia-scripts.md
+++ b/docs/authelia-scripts.md
@@ -12,10 +12,14 @@ Then, you can access the scripts usage by running the following command:
authelia-scripts --help
-For instance, you can build Authelia with:
+For instance, you can build Authelia (Go binary and frontend) with:
authelia-scripts build
+Or build the official Docker image with:
+
+ authelia-scripts docker build
+
Or start the *Standalone* suite with:
authelia-scripts suites setup Standalone
diff --git a/docs/build-and-dev.md b/docs/build-and-dev.md
index b3a7582c..9abe0083 100644
--- a/docs/build-and-dev.md
+++ b/docs/build-and-dev.md
@@ -1,53 +1,83 @@
# Build and dev
-**Authelia** is written in Go and comes with a dedicated CLI called [authelia-scripts](./authelia-scripts.md)
-which is available after running `source bootstrap.sh`. This CLI provides many useful tools to help you during
-development.
+**Authelia** is written in Go and comes with a dedicated CLI called
+[authelia-scripts](./authelia-scripts.md) which is available after
+running `source bootstrap.sh`. This CLI provides many useful tools
+to help you during development.
-In order to build and contribute to **Authelia**, you need to make sure Go v1.13, Docker,
-docker-compose and Node with version >= 8 and < 12 are installed on your machine.
+In order to build and contribute to **Authelia**, you need to make
+sure Go v1.13, Docker, docker-compose and Node v12 are installed on
+your machine.
## Get started
-**Authelia** is made of Go application serving the API and a [React](https://reactjs.org/)
-application for the portal.
+**Authelia** is made of Go application serving the API and a
+[React](https://reactjs.org/) application for the portal.
-In order to ease development, Authelia uses the concept of [suites] to run Authelia from source
-code so that your patches are included. This is a kind of virtual environment running **Authelia**
-in a complete ecosystem (LDAP, Redis, SQL server). Note that Authelia is hotreloaded in the
-environment so that your patches are instantly included.
+In order to ease development, Authelia uses the concept of [suites] to
+run Authelia from source code so that your patches are included. This
+is a kind of virtual environment running **Authelia** in a complete
+ecosystem (LDAP, Redis, SQL server). Note that Authelia is hotreloaded
+in the environment so that your patches are instantly included.
The next command starts the suite called *Standalone*:
- authelia-scripts suites setup Standalone
+ $ authelia-scripts suites setup Standalone
-Most of the suites are using docker-compose to bootstrap the environment. Therefore, you
-can check the logs of all application by running the following command on the component
-you want to monitor.
+Most of the suites are using docker-compose to bootstrap the
+environment. Therefore, you can check the logs of all application
+by running the following command on the component you want to
+monitor.
- docker logs authelia_authelia-backend_1 -f
+ $ docker logs authelia_authelia-backend_1 -f
-Then, edit the code and observe how **Authelia** is automatically reloaded.
+Then, edit the code and observe how **Authelia** is automatically
+reloaded.
### Unit tests
To run the unit tests, run:
- authelia-scripts unittest
+ $ authelia-scripts unittest
### Integration tests
-Integration tests are located under the `suites` directory based on Selenium.
+Integration tests are located under the `internal/suites` directory
+and are based on Selenium. A suite is a combination of environment
+and tests. Executing a suite therefore means starting the environment,
+running the tests and tearing down the environment. Each step can be
+run independantly:
- authelia-scripts suites test
+ # List the available suites
+ $ authelia-scripts suites list
+ Standalone
+ DuoPush
+ LDAP
+ Traefik
-You don't need to start the suite before testing it. Given you're not running
-any suite, just use the following command to test the *Standalone* suite.
+ # Start the environment of Standalone suite.
+ $ authelia-scripts suites setup Standalone
- authelia-scripts suites test Standalone
+ # Run the tests related to the currently running suite.
+ $ authelia-scripts suites test
-The suite will be spawned, tests will be run and then the suite will be teared down
-automatically.
+ # Tear down the environment
+ $ authelia-scripts suites teardown Standalone
+
+
+In order to test all suites (approx 30 minutes), you need to make
+sure there is no currently running suite and then you should run:
+
+ $ authelia-scripts suites test
+
+Also, you don't need to start the suite before testing it. Given
+you're not running any suite, just use the following command to
+test the *Standalone* suite.
+
+ $ authelia-scripts suites test Standalone
+
+The suite will be spawned, tests will be run and then the suite
+will be teared down automatically.
[suites]: ./suites.md
diff --git a/docs/configuration.md b/docs/configuration.md
index 4fafa798..45aca28c 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,11 +1,12 @@
# Configuration
Authelia is highly configurable thanks to a configuration file.
-There is a documented template configuration, called [config.template.yml](./config.template.yml), at
-the root of the repository. All the details are documented there.
+There is a documented template configuration, called
+[config.template.yml](./config.template.yml), at the root of the
+repository. All the details are documented there.
When running **Authelia**, you can specify your configuration file by passing
the file path as the first argument of **Authelia**.
- authelia config.custom.yml
+ $ authelia -config config.custom.yml
diff --git a/docs/deployment-dev.md b/docs/deployment-dev.md
index 4a8d47c5..80343ad3 100644
--- a/docs/deployment-dev.md
+++ b/docs/deployment-dev.md
@@ -16,8 +16,8 @@ non resilient to failures.*
**NOTE:** If not done already, we highly recommend you first follow the
[Getting Started] documentation.
-In some cases, like protecting personal projects/websites, it can be fine to use
-**Authelia** in a non highly-available setup. This reduces the number
+In some cases, like protecting personal projects/websites, it can be fine
+to use **Authelia** in a non highly-available setup. This reduces the number
of components to only two: a reverse proxy such as nginx or Traefik and
Authelia as a companion of the proxy.
@@ -26,17 +26,18 @@ either by pulling the Docker image or building distributable version.
## Build and deploy the distributable version
- authelia-scripts build
- PUBLIC_DIR=./dist/public_html ./dist/authelia -config /path/to/your/config.yml
+ $ authelia-scripts build
+ $ PUBLIC_DIR=./dist/public_html ./dist/authelia -config /path/to/your/config.yml
## Deploy with Docker
- docker pull clems4ever/authelia
- docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
+ $ docker pull clems4ever/authelia
+ $ docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
## Deploy Nginx
-You also need to install nginx and take [example/compose/nginx/minimal/nginx.conf](./example/compose/nginx/minimal/nginx.conf)
+You also need to install nginx and take
+[example/compose/nginx/minimal/nginx.conf](./example/compose/nginx/minimal/nginx.conf)
as an example for your configuration.
## Deploy Traefik
@@ -47,11 +48,12 @@ TODO
### Discard SQL server
-There is an option in the configuration file to avoid using an external SQL server
-and use a local sqlite3 database instead. This option will therefore prevent you
-from running multiple instances of **Authelia** in parallel.
-Consequently, this option is not meant to be used in production or at least
-not one that should scale out.
+There is an option in the configuration file to avoid using an external
+SQL server and use a local sqlite3 database instead. This option will
+therefore prevent you from running multiple instances of **Authelia**
+in parallel.
+Consequently, this option is not meant to be used in production or at
+least not one that should scale out.
Here is the configuration you should use:
@@ -88,8 +90,8 @@ from running multiple instances of **Authelia** in parallel and is therefore
discouraged for production environments.
To use a file backend instead of a LDAP server, you should first duplicate
-the file [users_database.yml](../test/suites/basic/users_database.yml) and edit it to add the
-users you want.
+the file [users_database.yml](../test/suites/basic/users_database.yml) and
+edit it to add the users you want.
The content of this file is as follows:
@@ -106,7 +108,7 @@ The password is hashed and salted as it is in LDAP servers with salted SHA-512
(more hash algorithms such as Argon2 will be provided in the future).
Here is a one-liner to generate such hashed password:
- $ authelia-scripts hash-password mypassword
+ $
$6$rounds=50000$BpLnfgDsc2WD8F2q$PumMwig8O0uIe9SgneL8Cm1FvUniOzpqBrH.uQE3aZR4K1dHsQldu5gEjJZsXcO./v3itfz6CXTDTJgeh5e8t.
Copy this newly hashed password into your `users_database.yml` file, prefixed with
diff --git a/docs/deployment-production.md b/docs/deployment-production.md
index 67555cd3..a86db6e8 100644
--- a/docs/deployment-production.md
+++ b/docs/deployment-production.md
@@ -31,18 +31,17 @@ the root of the repo.
### Deploy with the distributable version
# Build it if not done already
- authelia-scripts build
-
- PUBLIC_DIR=./dist/public_html authelia -config /path/to/your/config.yml
+ $ authelia-scripts build
+ $ PUBLIC_DIR=./dist/public_html authelia -config /path/to/your/config.yml
### Deploy With Docker
- docker run -v /path/to/your/config.yml:/etc/authelia/config.yml -e TZ=Europe/Paris clems4ever/authelia
+ $ docker run -v /path/to/your/config.yml:/etc/authelia/config.yml -e TZ=Europe/Paris clems4ever/$ $ authelia -config /etc/authelia/config.yml
## On top of Kubernetes
-
+
**Authelia** can also be installed on top of [Kubernetes] using
[nginx ingress controller](https://github.com/kubernetes/ingress-nginx).
diff --git a/docs/features.md b/docs/features.md
index f811973e..78e091af 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -1,6 +1,6 @@
# Features in details
-## First factor using a LDAP server
+## 1-Factor (1FA) using a LDAP server
**Authelia** uses an LDAP server as the backend for storing credentials.
When authentication is needed, the user is redirected to the login page which
@@ -11,11 +11,11 @@ You can find an example of the configuration of the LDAP backend in
[config.template.yml].
- 
+ 
-## Second factor
+## 2-Factor (2FA)
**Authelia** comes with three kind of second factor.
@@ -24,7 +24,7 @@ You can find an example of the configuration of the LDAP backend in
* Duo Push Notifications to use with [Duo mobile application](https://play.google.com/store/apps/details?id=com.duosecurity.duomobile&hl=en) available on Android, iOS and Windows. More info [here](./2factor/duo-push-notifications.md).
- 
+ 
## Password reset
@@ -37,7 +37,7 @@ email to the user email address.
Proceed with the password reset form and validate to reset your password.
- 
+ 
## Access Control
@@ -63,7 +63,7 @@ Please note that Authelia uses the *Proxy-Authorization* header and not
Authelia and the proxy. For instance you can use the following command to
access your service:
- curl -H "Proxy-Authorization: Basic am9objpwYXNzd29yZA==" https://myservice.example.com"
+ $ curl -H "Proxy-Authorization: Basic am9objpwYXNzd29yZA==" https://myservice.example.com"
## Session management with Redis
diff --git a/docs/getting-started.md b/docs/getting-started.md
index d6bc2163..54f5fc49 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -5,11 +5,11 @@
In order to deploy the current version of Authelia locally, run the following
command and follow the instructions of bootstrap.sh:
- source bootstrap.sh
+ $ source bootstrap.sh
Then, start the *Standalone* [suite].
- authelia-scripts suites setup Standalone
+ $ authelia-scripts suites setup Standalone
A [suite] is kind of a virtual environment for running Authelia in a complete ecosystem.
If you want more details please read the related [documentation](./suites.md).
@@ -28,20 +28,21 @@ normal to see this exception several times.
Below is what the login page looks like after you accepted all exceptions:
-
+
-You can use one of the users listed in [https://home.example.com:8080/](https://home.example.com:8080/).
+You can use one of the users listed in
+[https://home.example.com:8080/](https://home.example.com:8080/).
The rights granted to each user and group is also provided in the page as
a list of rules.
At some point, you'll be required to register your second factor device.
Since your security is **Authelia**'s priority, it will send
an email to the email address of the user to confirm the user identity.
-Since we're running a test environment, we provide a fake webmail called
-*MailCatcher* from which you can checkout the email and confirm
-your identity.
-The webmail is accessible from
+Since you are running a test environment, a fake webmail called
+*MailCatcher* has been deployed for you to check out the email and
+confirm your identity.
+The webmail is accessible at
[http://mail.example.com:8080](http://mail.example.com:8080).
Enjoy!
@@ -60,7 +61,7 @@ Here are the versions used for testing in Travis:
### How am I supposed to access the subdomains of example.com?
-Well, in order to test Authelia, Authelia fakes your browser by adding entries
+In order to test Authelia, Authelia fakes your browser by adding entries
in /etc/hosts when you first source the bootstrap.sh script.
### What should I do if I want to contribute?
diff --git a/docs/images/1FA.png b/docs/images/1FA.png
new file mode 100644
index 00000000..e28a104d
Binary files /dev/null and b/docs/images/1FA.png differ
diff --git a/docs/images/2FA-METHODS.png b/docs/images/2FA-METHODS.png
new file mode 100644
index 00000000..24d9e30d
Binary files /dev/null and b/docs/images/2FA-METHODS.png differ
diff --git a/docs/images/2FA-PUSH.png b/docs/images/2FA-PUSH.png
new file mode 100644
index 00000000..550e6593
Binary files /dev/null and b/docs/images/2FA-PUSH.png differ
diff --git a/docs/images/2FA-TOTP.png b/docs/images/2FA-TOTP.png
new file mode 100644
index 00000000..b12bbf8e
Binary files /dev/null and b/docs/images/2FA-TOTP.png differ
diff --git a/docs/images/2FA-U2F.png b/docs/images/2FA-U2F.png
new file mode 100644
index 00000000..e6e7708e
Binary files /dev/null and b/docs/images/2FA-U2F.png differ
diff --git a/docs/images/REGISTER-TOTP.png b/docs/images/REGISTER-TOTP.png
new file mode 100644
index 00000000..695ab82b
Binary files /dev/null and b/docs/images/REGISTER-TOTP.png differ
diff --git a/docs/images/REGISTER-U2F.png b/docs/images/REGISTER-U2F.png
new file mode 100644
index 00000000..2393bf5c
Binary files /dev/null and b/docs/images/REGISTER-U2F.png differ
diff --git a/docs/images/RESET-PASSWORD-STEP1.png b/docs/images/RESET-PASSWORD-STEP1.png
new file mode 100644
index 00000000..577c7d96
Binary files /dev/null and b/docs/images/RESET-PASSWORD-STEP1.png differ
diff --git a/images/authelia-title.png b/docs/images/authelia-title.png
similarity index 100%
rename from images/authelia-title.png
rename to docs/images/authelia-title.png
diff --git a/images/authelia-title.xcf b/docs/images/authelia-title.xcf
similarity index 100%
rename from images/authelia-title.xcf
rename to docs/images/authelia-title.xcf
diff --git a/images/duo-push-1.jpg b/docs/images/duo-push-1.jpg
similarity index 100%
rename from images/duo-push-1.jpg
rename to docs/images/duo-push-1.jpg
diff --git a/images/duo-push-2.png b/docs/images/duo-push-2.png
similarity index 100%
rename from images/duo-push-2.png
rename to docs/images/duo-push-2.png
diff --git a/images/authelia.logo.png b/docs/images/logos/authelia.logo.png
similarity index 100%
rename from images/authelia.logo.png
rename to docs/images/logos/authelia.logo.png
diff --git a/images/docker.logo.png b/docs/images/logos/docker.logo.png
similarity index 100%
rename from images/docker.logo.png
rename to docs/images/logos/docker.logo.png
diff --git a/images/kubernetes.logo.png b/docs/images/logos/kubernetes.logo.png
similarity index 100%
rename from images/kubernetes.logo.png
rename to docs/images/logos/kubernetes.logo.png
diff --git a/images/nginx.logo.png b/docs/images/logos/nginx.logo.png
similarity index 100%
rename from images/nginx.logo.png
rename to docs/images/logos/nginx.logo.png
diff --git a/images/traefik.logo.png b/docs/images/logos/traefik.logo.png
similarity index 100%
rename from images/traefik.logo.png
rename to docs/images/logos/traefik.logo.png
diff --git a/images/plus.png b/docs/images/plus.png
similarity index 100%
rename from images/plus.png
rename to docs/images/plus.png
diff --git a/images/user.svg b/docs/images/user.svg
similarity index 100%
rename from images/user.svg
rename to docs/images/user.svg
diff --git a/docs/security.md b/docs/security.md
index 88498324..7d69a560 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -2,7 +2,7 @@
## Protection against cookie theft
-Authelia uses two mechanism to protect against cookie theft:
+Authelia uses two mechanisms to protect against cookie theft:
1. session attribute `httpOnly` set to true make client-side code unable to
read the cookie.
2. session attribute `secure` ensure the cookie will never be sent over an
@@ -21,14 +21,6 @@ that the attacker must also require the certificate to retrieve the cookies.
Note that using [HSTS] has consequences. That's why you should read the blog
post nginx has written on [HSTS].
-## Content-Security-Policy
-
-Authelia's portal is protected against some XSS using the content
-security policy mechanism that is documented
-[here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). This protection
-will reject untrusted payloads threatening your users during the authentication
-workflow.
-
## More protections measures with Nginx
You can also apply the following headers to your nginx configuration for
diff --git a/docs/suites.md b/docs/suites.md
index 386ea538..90db91d1 100644
--- a/docs/suites.md
+++ b/docs/suites.md
@@ -1,46 +1,39 @@
# Suites
-Authelia is a single component in interaction with many others. Consequently, testing the features
-is not as easy as we might think. In order to solve this problem, Authelia came up with the concept of
-suite which is a kind of virtual environment for Authelia, it allows to create an environment made of
-components such as nginx, redis or mariadb in which Authelia can run and be tested.
+Authelia is a single component in interaction with many others in a complete
+ecosystem. Consequently, testing the features is not as easy as we might
+think. In order to solve this problem, Authelia came up with the concept of
+suite which is a kind of virtual environment for Authelia and a set of tests.
+A suite can setup components such as nginx, redis or mariadb in which
+Authelia can run and be tested.
-This abstraction allows to prepare an environment for manual testing during development and also to
-craft and run integration tests efficiently.
+This abstraction allows to prepare an environment for manual testing during
+development and also to craft and run integration tests efficiently.
## Start a suite.
Starting a suite called *Standalone* is done with the following command:
- authelia-scripts suites setup Standalone
+ $ authelia-scripts suites setup Standalone
-It will deploy the environment of the suite and block until you hit ctrl-c to stop the suite.
+This command deploys the environment of the suite.
## Run tests of a suite
### Run tests of running suite
-If a suite is already running, you can simply type:
+If a suite is already running, you can simply type the test command
+that will run the test related to the currently running suite:
- authelia-scripts suites test
-
-and this will run the tests related to the running suite.
+ $ authelia-scripts suites test
### Run tests of non-running suite
-However, if no suite is running and you still want to test a particular suite like *HighAvailability*.
-You can do so with the next command:
+However, if no suite is running yet and you just want to run the tests of a
+specific suite like *HighAvailability*, you can do so with the next command:
- authelia-scripts suites test HighAvailability
-
-This command will run the tests for the *HighAvailability* suite. Beware that running tests of a
-non-running suite implies the tests run against the distributable version of Authelia instead of
-the current development version. If you made some patches, you must build the distributable version
-before running the test command:
-
- # Build authelia before running the tests against the suite.
- authelia-scripts build
- authelia-scripts docker build
+ # Set up the env, run the tests and tear down the env
+ $ authelia-scripts suites test HighAvailability
### Run all tests of all suites
@@ -48,26 +41,25 @@ Running all tests is easy. Make sure that no suite is already running and run:
authelia-scripts suites test
-Beware that the distributable version of Authelia is tested in that case. Don't
-forget to build Authelia including your patches before running the command.
-
-
- # Build authelia before running the tests against the suite.
- authelia-scripts build
- authelia-scripts docker build
-
### Run tests in headless mode
-In order to run the tests in headless mode, use the following command:
+As you might have noticed, the tests are run using chromedriver and selenium. It means
+that the tests open an instance of Chrome that might interfere with your other activities.
+In order to run the tests in headless mode to avoid the interference, use the following
+command:
- authelia-scripts suites test --headless
+ $ authelia-scripts suites test --headless
## Create a suite
-Creating a suite is as easy as creating a new directory with at least two files:
+Creating a suite is as easy. Let's take the example of the **Standalone** suite:
-* **environment.ts** - It defines the setup and teardown phases when creating the environment. The *setup*
-phase is the phase when the required components will be spawned and Authelia will start while the *teardown*
-is executed when the suite is destroyed (ctrl-c hit by the user) or the tests are finished.
-* **test.ts** - It defines a set of tests to run against the suite.
\ No newline at end of file
+* **suite_standalone.go** - It defines the setup and teardown phases. It likely uses
+docker-compose to setup the ecosystem. This file also defines the timeouts.
+* **suite_standalone_test.go** - It defines the set of tests to run against the suite.
+* **Standalone** directory - It contains resources required by the suite and likely
+mounted in the containers.
+
+A suite can also be much more complex like setting up a complete Kubernetes ecosystem.
+You can check the Kubernetes suite as example.
\ No newline at end of file
diff --git a/images/2factor_duo.png b/images/2factor_duo.png
deleted file mode 100644
index f68d1b48..00000000
Binary files a/images/2factor_duo.png and /dev/null differ
diff --git a/images/2factor_totp.png b/images/2factor_totp.png
deleted file mode 100644
index d09a8f2e..00000000
Binary files a/images/2factor_totp.png and /dev/null differ
diff --git a/images/2factor_u2f.png b/images/2factor_u2f.png
deleted file mode 100644
index 8cdd2d83..00000000
Binary files a/images/2factor_u2f.png and /dev/null differ
diff --git a/images/email_confirmation.png b/images/email_confirmation.png
deleted file mode 100644
index 2e07c213..00000000
Binary files a/images/email_confirmation.png and /dev/null differ
diff --git a/images/first_factor.png b/images/first_factor.png
deleted file mode 100644
index 60330118..00000000
Binary files a/images/first_factor.png and /dev/null differ
diff --git a/images/reset_password.png b/images/reset_password.png
deleted file mode 100644
index 6a3e55d8..00000000
Binary files a/images/reset_password.png and /dev/null differ
diff --git a/images/second_factor.png b/images/second_factor.png
deleted file mode 100644
index 3f717cac..00000000
Binary files a/images/second_factor.png and /dev/null differ
diff --git a/images/totp.png b/images/totp.png
deleted file mode 100644
index 2716b2d1..00000000
Binary files a/images/totp.png and /dev/null differ
diff --git a/images/u2f.png b/images/u2f.png
deleted file mode 100644
index 20186f2b..00000000
Binary files a/images/u2f.png and /dev/null differ
diff --git a/images/use-another-method.png b/images/use-another-method.png
deleted file mode 100644
index 560679b6..00000000
Binary files a/images/use-another-method.png and /dev/null differ