From 06aa9803bf5a25179d7750d99d4500e43c8cea0b Mon Sep 17 00:00:00 2001 From: Clement Michaud Date: Sun, 3 Mar 2019 00:25:40 +0100 Subject: [PATCH] Update the documentation to include info about suites and authelia-scripts. --- docs/authelia-scripts.md | 20 +++++++++++ docs/build.md | 66 ++++++++++++----------------------- docs/deployment-dev.md | 23 +++++++----- docs/deployment-production.md | 18 +++++----- docs/getting-started.md | 22 +++++++----- docs/security.md | 8 +++++ docs/suites.md | 55 +++++++++++++++++++++++++++++ package.json | 3 +- test/suites/README.md | 56 ++--------------------------- 9 files changed, 148 insertions(+), 123 deletions(-) create mode 100644 docs/authelia-scripts.md create mode 100644 docs/suites.md diff --git a/docs/authelia-scripts.md b/docs/authelia-scripts.md new file mode 100644 index 000000000..460ccb54d --- /dev/null +++ b/docs/authelia-scripts.md @@ -0,0 +1,20 @@ +# Authelia Scripts + +Authelia comes with a set of dedicated scripts doing a broad range of operations such as +building the distributed version of Authelia, building the Docker image, running suites, +testing the code, etc... + +You can access the scripts usage by running the following command: + + npm run scripts + +For instance, you can build Authelia with: + + npm run scripts build + +Or start the *basic* suite with: + + npm run scripts suites start basic + + +You will find more information in the scripts usage helpers. \ No newline at end of file diff --git a/docs/build.md b/docs/build.md index 9437d1f63..23dbaa81c 100644 --- a/docs/build.md +++ b/docs/build.md @@ -1,73 +1,53 @@ # Build -**Authelia** is written in Typescript and built with [Grunt](https://gruntjs.com/). +**Authelia** is written in Typescript and built with [Authelia scripts](docs/authelia-scripts.md). -In order to build **Authelia**, you need to make sure Node v8 and NPM is +In order to build **Authelia**, you need to make sure Node with version >= 8 and < 10 and NPM is installed on your machine. -Then, run the following command install the node modules: +Then, run the following command to install the node modules: npm install And, this command to build **Authelia** under dist/: - ./node_modules/.bin/grunt build + npm run build + +Then you can also build the Docker image with: + + npm run docker build ## Details ### Build -**Authelia** is made of two components: the client and the server. +**Authelia** is made of two parts: the frontend and the backend. -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 also built as part of the global `build` -Grunt command. +The frontend is a [React](https://reactjs.org/) application written in Typescript and +the backend is an express application also written in Typescript. ### Tests -Grunt also handles the commands to run the tests. There are several type of -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. +There are two kind of tests: unit tests and integration tests. ### Unit tests -To run the client unit tests, run: +To run the unit tests, run: - ./node_modules/.bin/grunt test-client - -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 + npm run unittest ### Integration tests -Integration tests are mainly based on Selenium so they -need a complete environment to be run. +Integration tests run with Mocha and are based on Selenium. They generally +require a complete environment made of several components like redis, mongo and a LDAP +to run. -You can start by making sure **Authelia** is built with: +In order to simplify the creation of such environments, Authelia comes with a concept of +[Suites] that basically act as virtual environments for running either +manual or integration tests. - grunt build +Please read the documentation related to [Suites] in order to discover +how to run related tests. -and the docker image is built with: - ./scripts/example-commit/dc-example.sh build - -Then, start the environment with: - - ./scripts/example-commit/dc-example.sh up -d - -And run the tests with: - - ./node_modules/.bin/grunt test-int - -Note: the Cucumber tests are hard to maintain and will therefore -be refactored to use Mocha instead. +[Suites]: ./suites.md \ No newline at end of file diff --git a/docs/deployment-dev.md b/docs/deployment-dev.md index 194647f49..144588726 100644 --- a/docs/deployment-dev.md +++ b/docs/deployment-dev.md @@ -17,9 +17,9 @@ non resilient to failures.* [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. +**Authelia** in a non highly-available setup. We can +achieve that in order to reduce the number of components to only two: 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 @@ -37,7 +37,8 @@ it with a configuration file passed as argument. ## Deploy Nginx -You also need to install nginx and take [example/compose/nginx/minimal/nginx.conf](./example/compose/nginx/minimal/nginx.conf) as an example of configuration. +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. ## Discard components @@ -83,7 +84,7 @@ 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 +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: @@ -99,10 +100,10 @@ The content of this file is as follows: 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)))' + npm run hash-password mypassword Once the file is created, edit the configuration file with the following -block (as used in [config.minimal.yml](../config.minimal.yml)): +block (as used in [config.yml](../test/suites/basic/config.yml)): authentication_backend: file: @@ -141,9 +142,13 @@ 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? +### Why aren't all those steps 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. +writing an Ansible playbook to automate all this process is ok. We would really be more than happy to review such a PR. +In the meantime, you can check the *basic* [suite](./suites.md) to see all this +in real example. + +[Getting Started]: ./getting-started.md diff --git a/docs/deployment-production.md b/docs/deployment-production.md index 835adb934..94c2cded7 100644 --- a/docs/deployment-production.md +++ b/docs/deployment-production.md @@ -36,17 +36,12 @@ the root of the repo. -**Authelia** can also be used on top of [Kubernetes] using [nginx ingress -controller](https://github.com/kubernetes/ingress-nginx). +**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? @@ -55,4 +50,11 @@ 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 +Again, we would be glad to review any PR implementing this. + + + +[config.template.yml]: ../config.template.yml +[Getting Started]: ./getting-started.md +[Deployment for Devs]: ./deployment-dev.md +[Kubernetes]: https://kubernetes.io/ diff --git a/docs/getting-started.md b/docs/getting-started.md index 758a3d15e..d6f6882f5 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -26,16 +26,17 @@ Here are the versions used for testing in Travis: Make sure you don't have anything listening on port 8080 and 8085. -The port 8080 will be our frontend load balancer serving both **Authelia**'s portal and the applications we want to protect. +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 fake emails sent by **Authelia** +The port 8085 is serving a webmail used to receive emails sent by **Authelia** to validate your identity when registering U2F or TOTP secrets or when resetting your password. ### Subdomain aliases -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 +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 @@ -52,7 +53,10 @@ subdomains so that nginx can redirect requests to the correct virtual host. To deploy **Authelia** using the latest image from [Dockerhub], run the following command: - ./scripts/example-dockerhub/deploy-example.sh + npm run script suites start dockerhub + +A Suites is a virtual environment for running Authelia. If you want more details please +read the related [documentation](./suites.md). ## Test it! @@ -71,8 +75,8 @@ 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/). The rights granted to each user and -group is also provided there. +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 @@ -86,8 +90,8 @@ The webmail is accessible from **Note:** If you cannot deploy the fake webmail for any reason. You can configure **Authelia** to use the filesystem notifier (option available in [config.template.yml]) that will send the content of the email in a -file instead of sending an email. It is advised to use this option -for testing only. +file instead of sending an email. It is advised to not use this option +in production. Enjoy! diff --git a/docs/security.md b/docs/security.md index e1298dce0..b2e1e2c02 100644 --- a/docs/security.md +++ b/docs/security.md @@ -21,6 +21,14 @@ 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 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 new file mode 100644 index 000000000..03a528213 --- /dev/null +++ b/docs/suites.md @@ -0,0 +1,55 @@ +# Suites + +Authelia is a single component in interaction with many others. Consequently, testing the features +is not as easy as we might think. Consequently, a suite is kind of a virtual environment for Authelia, +it allows to create an environment made of components such as nginx, redis or mongo 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. + +## Start a suite. + +Starting a suite called *simple* is done with the following command: + + npm run scripts suites start simple + +It will start the suite and block until you hit ctrl-c to stop the suite. + +## Run tests of a suite + +### Run tests of running suite + +If you are already running a suite with the previous command, you can simply type: + + npm run scripts test + +and this will run the tests related to the running suite. + +### Run tests of non-running suite + +However, if no suite is running and you still want to test a particular suite like *complete*. +You can do so with the next command: + + npm run scripts test complete + +This command will run the tests for the *complete* suite using the built version of Authelia that +should be located in *dist*. + +WARNING: Authelia must be built before running this command. + +### Run all tests of all suites + +Running all tests is as easy as making sure that there is no running suite and typing: + + npm run scripts test + + +## Create a suite + +Creating a suite is as easy as creating a new directory with at least two files: + +* **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). +* **test.ts** - It defines a set of tests to run in the virtual environment of the suite. \ No newline at end of file diff --git a/package.json b/package.json index de6e64f8e..d11dcf9f2 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,8 @@ "test": "./scripts/authelia-scripts suites test", "travis": "./scripts/authelia-scripts travis", "cover": "NODE_ENV=test nyc npm t", - "scripts": "./scripts/authelia-scripts" + "scripts": "./scripts/authelia-scripts", + "hash-password": "./scripts/authelia-scripts hash-password" }, "repository": { "type": "git", diff --git a/test/suites/README.md b/test/suites/README.md index 6629a2068..7558d99d2 100644 --- a/test/suites/README.md +++ b/test/suites/README.md @@ -1,55 +1,5 @@ # Authelia Suites -Authelia is a single component in interaction with many others. Consequently, testing the features -is not as easy as we might think. Consequently, a suite is kind of a virtual environment for Authelia, -it allows to create an environment made of components such as nginx, redis or mongo 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. - -## Start a suite. - -Starting a suite called *simple* is done with the following command: - - npm run scripts suites start simple - -It will start the suite and block until you hit ctrl-c to stop the suite. - -## Run tests of a suite - -### Run tests of running suite - -If you are already running a suite with the previous command, you can simply type: - - npm run scripts test - -and this will run the tests related to the running suite. - -### Run tests of non-running suite - -However, if no suite is running and you still want to test a particular suite like *complete*. -You can do so with the next command: - - npm run scripts test complete - -This command will run the tests for the *complete* suite using the built version of Authelia that -should be located in *dist*. - -WARNING: Authelia must be built before running this command. - -### Run all tests of all suites - -Running all tests is as easy as making sure that there is no running suite and typing: - - npm run scripts test - - -## Create a suite - -Creating a suite is as easy as creating a new directory with at least two files: - -* **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). -* **test.ts** - It defines a set of tests to run in the virtual environment of the suite. \ No newline at end of file +A **suite** is a kind of virtual environment for Authelia. Please +read the related documentation [here](../docs/suites.md) to get more +details. \ No newline at end of file