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

Add details on how to deploy Authelia in a dev environment.

Browse Source 
Also improve some part of the documentation.
This commit is contained in:
Clement Michaud 2018-11-16 08:39:57 +01:00
parent 82e51e1a71
commit de15dc52dd
8 changed files with 261 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
README.md
View File

@ -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

16
docs/build.md
View File

@ -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

2
docs/configuration.md
View File

@ -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

149
docs/deployment-dev.md Normal file
View File

@ -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.

58
docs/deployment-production.md Normal file
View File

@ -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
<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).
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.

43
docs/deployment.md
View File

@ -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
<img src="/images/kube-logo.png" width="24" align="left">
**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

2
docs/features.md
View File

@ -11,7 +11,7 @@ You can find an example of the configuration of the LDAP backend in
[config.template.yml].
<p align="center">
<img src="../images/second_factor.png" width="400">
<img src="../images/first_factor.png" width="400">
</p>

63
docs/getting-started.md
View File

@ -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:
<p align="center">
<img src="../images/first_factor.png" width="400">
</p>
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