From de15dc52ddaf12d0b7352df71a9077a842d4bee3 Mon Sep 17 00:00:00 2001 From: Clement Michaud Date: Fri, 16 Nov 2018 08:39:57 +0100 Subject: [PATCH] Add details on how to deploy Authelia in a dev environment. Also improve some part of the documentation. --- README.md | 23 +++--- docs/build.md | 16 ++-- docs/configuration.md | 2 +- docs/deployment-dev.md | 149 ++++++++++++++++++++++++++++++++++ docs/deployment-production.md | 58 +++++++++++++ docs/deployment.md | 43 ---------- docs/features.md | 2 +- docs/getting-started.md | 63 +++++++------- 8 files changed, 261 insertions(+), 95 deletions(-) create mode 100644 docs/deployment-dev.md create mode 100644 docs/deployment-production.md delete mode 100644 docs/deployment.md diff --git a/README.md b/README.md index 748a4656..59107576 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,14 @@ For more details about the features, follow [Features](./docs/features.md). ## Getting Started -Follow [Getting Started](./docs/getting-started.md). +If you want to quickly test Authelia with Docker, we recommend you 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](./docs/deployment-production.md). This guide will show you how to deploy +it on bare metal as well as on Kubernetes. ## Security @@ -49,15 +56,6 @@ 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](./docs/security.md). -## Deployment - -To learn how to deploy **Authelia** or use it on Kubernetes, please follow -[Deployment](./docs/deployment.md). - -## Build Authelia - -Follow [Build](./docs/build.md). - ## Changelog See [CHANGELOG.md](CHANGELOG.md). @@ -71,6 +69,11 @@ or review pull requests and take part to discussions in We are already greatful to contributors listed in [CONTRIBUTORS.md](CONTRIBUTORS.md) for their contributions to the project. +Be the next in the list! + +## Build Authelia + +If you want to contribute with code, you should follow the documentation explaining how to [build](./docs/build.md) the application. ## Donation diff --git a/docs/build.md b/docs/build.md index ca564f42..9437d1f6 100644 --- a/docs/build.md +++ b/docs/build.md @@ -1,6 +1,6 @@ # Build -**Authelia** is written in Typescript and built with Grunt. +**Authelia** is written in Typescript and built with [Grunt](https://gruntjs.com/). In order to build **Authelia**, you need to make sure Node v8 and NPM is installed on your machine. @@ -22,14 +22,14 @@ And, this command to build **Authelia** under dist/: The client is written in Typescript and uses jQuery. It is built as part of the global `build` Grunt command. -The server is written in Typescript. It is built as part of the global `build` +The server is written in Typescript. It is also built as part of the global `build` Grunt command. ### Tests Grunt also handles the commands to run the tests. There are several type of -tests for **Authelia**: unit tests for the server, unit tests for the client -and integration tests for both. +tests for **Authelia**: unit tests for the server, the client and a shared +library and an integration test suite testing both components together. The unit tests are written with Mocha while integration tests are using Cucumber and Mocha. @@ -44,12 +44,16 @@ To run the server unit tests, run: ./node_modules/.bin/grunt test-server +To run the shared library unit tests, run: + + ./node_modules/.bin/grunt test-shared + ### Integration tests Integration tests are mainly based on Selenium so they -need a complete environment to be set up. +need a complete environment to be run. -Start by making sure **Authelia** is built with: +You can start by making sure **Authelia** is built with: grunt build diff --git a/docs/configuration.md b/docs/configuration.md index 4c3f43fb..4fafa798 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,7 +1,7 @@ # Configuration Authelia is highly configurable thanks to a configuration file. -There is a documented template configuration, called [config.template.yml], at +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 diff --git a/docs/deployment-dev.md b/docs/deployment-dev.md new file mode 100644 index 00000000..59abc41a --- /dev/null +++ b/docs/deployment-dev.md @@ -0,0 +1,149 @@ +# Deployment for Dev + +1. [Deploy With npm](#deploy-with-npm) +2. [Deploy With Docker](#deploy-with-docker) +3. [Deploy nginx](#deploy-nginx) +4. [Discard components](#discard-components) + 1. [Discard MongoDB](#discard-mongodb) + 2. [Discard Redis](#discard-redis) + 3. [Discard LDAP](#discard-ldap) +5. [FAQ](#faq) + +***WARNING:** the instructions given in this documentation are not meant +to be used for production environments since it will make **Authelia** +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 websites, it can be fine to use +**Authelia** in a non highly-available manner. Fortunately, we can +achieve to run it along with one reverse proxy meaning the setup is +then reduced to only two components: Authelia and nginx. + +As for a regular deployment in production, you need to install **Authelia** +either by pulling the Docker image or installing the npm package and run +it with a configuration file passed as argument. + +## Deploy with npm + + npm install -g authelia + authelia /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 + +## Deploy Nginx + +You also need to install nginx and take [example/nginx/minimal/nginx.conf](./example/nginx/minimal/nginx.conf) as an example of configuration. + +## Discard components + +### Discard MongoDB + +There is an option in the configuration file to discard MongoDB and use +your local filesystem to store the database data. 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. + +Here is the configuration block you should use: + + storage: + # The directory where the DB files will be saved + local: + path: /var/lib/authelia/store + +### Discard Redis + +There is an option in the configuration file to discard Redis and use the +memory of the server to store the KV data. This option will therefore +prevent you from running multiple instances of **Authelia** in parallel and +will make you lose user sessions if the application restarts. This +concretely means that all your users will need to authenticate again in +that case. Hence, this option is not meant to be used in production. + +To use memory instead of a Redis backend, just comment out the Redis +connection details in the following block: + + session: + ... + # # The redis connection details + # redis: + # host: redis + # port: 6379 + # password: authelia + +### Discard LDAP + +**Authelia** can use a file backend in order to store users instead of a +LDAP server or an Active Directory. This mode will therefore prevent you +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](../users_database.yml) and edit it to add the +users you want. + +The content of this file is as follows: + + users: + ... + john: + password: "{CRYPT}$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/" + email: john.doe@authelia.com + groups: + - admins + - dev + +The password is hashed and salted as it is in LDAP servers with salted SHA-512. Here is a one-liner to generate such hashed password: + + python3 -c 'import crypt; print("{CRYPT}" + crypt.crypt("mypassword", crypt.mksalt(crypt.METHOD_SHA512, rounds=500000)))' + +Once the file is created, edit the configuration file with the following +block (as used in [config.minimal.yml](../config.minimal.yml)): + + authentication_backend: + file: + path: /etc/authelia/users_database.yml + +instead of (used in [config.template.yml](../config.template.yml)): + + authentication_backend: + ldap: + url: ldap://openldap + base_dn: dc=example,dc=com + + additional_users_dn: ou=users + users_filter: cn={0} + + additional_groups_dn: ou=groups + groups_filter: (&(member={dn})(objectclass=groupOfNames)) + + group_name_attribute: cn + + mail_attribute: mail + + user: cn=admin,dc=example,dc=com + password: password + +## FAQ + +### Can you give more details on why this is not suitable for production environments? + +This documentation gives instructions that will make **Authelia** non +highly-available and non scalable by preventing you from running multiple +instances of the application. +This means that **Authelia** won't be able to distribute the +load accross multiple servers and it will prevent failover in case of a +crash or an hardware issue. Moreover, it will also prevent from reliably +persisting data and consequently fail access to your platform as the devices +registered by your users will be lost. + +### Why is this not automated? + +Well, as stated before those instructions are not meant to be applied for +a production environment. That being said, in some cases it is just fine and +so writing an Ansible playbook to automate all this process would be great. +We would really be more than happy to review such a PR. \ No newline at end of file diff --git a/docs/deployment-production.md b/docs/deployment-production.md new file mode 100644 index 00000000..835adb93 --- /dev/null +++ b/docs/deployment-production.md @@ -0,0 +1,58 @@ +# Deployment for Production + +**Authelia** can be deployed on bare metal or on Kubernetes with two +different kind of artifacts: an npm package or a Docker image. + +**NOTE:** If not done already, we highly recommend you first follow the +[Getting Started] documentation. + +## On Bare Metal + +**Authelia** has been designed to be a proxy companion handling the +authentication and authorization requests for your entire infrastructure. + +As **Authelia** will be key in your architecture, it requires several +components to make it highly-available. Deploying it in production means having an LDAP server for storing the information about the users, a Redis cache to store the user sessions in a distributed manner, a +MongoDB to persist user configurations and one or more nginx reverse proxies configured to be used with Authelia. With such a setup **Authelia** can easily be scaled to multiple instances to evenly handle the traffic. + +**NOTE:** If you don't have all those components, don't worry, there is a way to deploy **Authelia** with only nginx. This is described in [Deployment for Devs]. + +Here are the available steps to deploy **Authelia** given +the configuration file is **/path/to/your/config.yml**. Note that you can +create your own configuration file from [config.template.yml] located at +the root of the repo. + +### Deploy With NPM + + npm install -g authelia + authelia /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 + +## On top of Kubernetes + + + +**Authelia** can also be used on top of [Kubernetes] using [nginx ingress +controller](https://github.com/kubernetes/ingress-nginx). + +Please refer to the following [documentation](../example/kube/README.md) +for more information. + +[config.template.yml]: ../config.template.yml +[Getting Started]: ./getting-started.md +[Deployment for Devs]: ./deployment-dev.md +[Kubernetes]: https://kubernetes.io/ + +## FAQ + +### Why is this not automated? + +Ansible would be a very good candidate to automate the installation of such +an infrastructure on bare metal. We would be more than happy to review any PR on that matter. + +Regarding Kubernetes, the right way to go would be to write a helm recipe. +Again, we would be glad to review any PR implementing this. \ No newline at end of file diff --git a/docs/deployment.md b/docs/deployment.md deleted file mode 100644 index 53c077ad..00000000 --- a/docs/deployment.md +++ /dev/null @@ -1,43 +0,0 @@ -# Deployment - -**Authelia** can be deployed in two different ways: npm and docker. - -Here are the available steps to deploy **Authelia** on your machine given -your configuration file is **/path/to/your/config.yml**. Note that you can -create your own the configuration file from [config.template.yml] at the root -of the repo. - -## Standalone - -**Authelia** has been designed to be a proxy companion handling the SSO. -Therefore, deploying it in production means having an LDAP, a Redis, a -MongoDB and one or more nginx running and configured to be used with -Authelia. - -If you don't have all of this, don't worry, there is a way to deploy -**Authelia** with only an nginx. To do so, please refer to the -[Getting Started]. Otherwise here are the command to run Authelia in your -environment. - -### With NPM - - npm install -g authelia - authelia /path/to/your/config.yml - -### With Docker - - docker pull clems4ever/authelia - docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia - -## Kubernetes - - - -**Authelia** can also be used on top of Kubernetes using the nginx ingress -controller. - -Please refer to the following [README](../example/kube/README.md) for more -information. - -[config.template.yml]: ../config.template.yml -[Getting Started]: ./getting-started.md diff --git a/docs/features.md b/docs/features.md index 98c4225a..98930922 100644 --- a/docs/features.md +++ b/docs/features.md @@ -11,7 +11,7 @@ You can find an example of the configuration of the LDAP backend in [config.template.yml].

- +

diff --git a/docs/getting-started.md b/docs/getting-started.md index 27163d65..758a3d15 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,17 +1,14 @@ # Getting Started **Authelia** can be tested in a matter of seconds with docker-compose based -on the latest image available on [Dockerhub] or by building the latest version -from the sources and use it in docker-compose. +on the latest image available on [Dockerhub]. ## Pre-requisites In order to test **Authelia**, we need to make sure that: -- **Docker** and **docker-compose** are installed. -- Some ports are open for listening on your machine. -- Some subdomains redirect to your machine to simulate the fact that some -applications you want to protect are served by some subdomains of -**example.com** on your machine. +- **Docker** and **docker-compose** are installed on your computer. +- Ports 8080 and 8085 are not already used on your machine. +- Some subdomains of **example.com** redirect to your test infrastructure. ### Docker & docker-compose @@ -19,30 +16,27 @@ Make sure you have **docker** and **docker-compose** installed on your machine. Here are the versions used for testing in Travis: - docker --version + $ docker --version + Docker version 17.03.1-ce, build c6d412e -gave *Docker version 17.03.1-ce, build c6d412e*. - - docker-compose --version - -gave *docker-compose version 1.14.0, build c7bdf9e*. + $ docker-compose --version + docker-compose version 1.14.0, build c7bdf9e ### Available port Make sure you don't have anything listening on port 8080 and 8085. -The port 8080 will be used by nginx to serve **Authelia** and the applications -we want to protect with **Authelia**. +The port 8080 will be our frontend load balancer serving both **Authelia**'s portal and the applications we want to protect. -The port 8085 is serving a webmail used to receive emails sent by **Authelia** +The port 8085 is serving a webmail used to receive fake emails sent by **Authelia** to validate your identity when registering U2F or TOTP secrets or when resetting your password. ### Subdomain aliases -Make sure the following subdomains redirect to your machine by adding the -following lines to your **/etc/hosts**. It will alias the subdomains so that -nginx can redirect requests to the correct virtual host. +In order to simulate the behavior of a DNS resolving some test subdomains of **example.com** to your machine, we +need to add the following lines to your **/etc/hosts**. It will alias the +subdomains so that nginx can redirect requests to the correct virtual host. 127.0.0.1 home.example.com 127.0.0.1 public.example.com @@ -53,40 +47,41 @@ nginx can redirect requests to the correct virtual host. 127.0.0.1 single_factor.example.com 127.0.0.1 login.example.com -## From Dockerhub +## Deploy To deploy **Authelia** using the latest image from [Dockerhub], run the following command: ./scripts/example-dockerhub/deploy-example.sh -## From source - -To deploy **Authelia** from source, follow the [build] manual and run the -following commands: - - ./scripts/example-commit/deploy-example.sh - ## Test it! After few seconds the services should be running and you should be able to visit [https://home.example.com:8080/](https://home.example.com:8080/). -When accessing the login page, a self-signed certificate exception should -appear, it has to be trusted before you can get to the home page. +When accessing the login page, since this is a test environment a +self-signed certificate exception should appear, it has to be trusted +before you can get to the home page. The certificate must also be trusted for each subdomain, therefore it is normal to see this exception several times. -Below is what the login page looks like: +Below is what the login page looks like after you accepted all exceptions:

-At some point, you'll be required to register a secret for setting up -the second factor. **Authelia** will send an email to the user email -address to confirm the user identity. In order to receive it, visit the -webmail at [http://localhost:8085](http://localhost:8085). +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 there. + +At some point, you'll be required to register your second factor, either +U2F or TOTP. 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 +[http://localhost:8085](http://localhost:8085). **Note:** If you cannot deploy the fake webmail for any reason. You can configure **Authelia** to use the filesystem notifier (option available