Update the documentation to include info about suites and authelia-scripts.
Clement Michaud
parent
27c4312709
commit
06aa9803bf
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -36,17 +36,12 @@ the root of the repo.
|
|||
|
||||
<img src="/images/kube-logo.png" width="24" align="left">
|
||||
|
||||
**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.
|
||||
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/
|
||||
|
|
|
|||
|
|
@ -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:
|
|||
<img src="../images/first_factor.png" width="400">
|
||||
</p>
|
||||
|
||||
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!
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
A **suite** is a kind of virtual environment for Authelia. Please
|
||||
read the related documentation [here](../docs/suites.md) to get more
|
||||
details.
|
||||
Loading…
Reference in New Issue