From a515ce83c758a38f9a32003d8d9182b533909473 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Michaud?= Date: Sun, 26 Aug 2018 23:46:15 +0200 Subject: [PATCH] Refactor README into several documents unders docs directory. (#265) --- README.md | 299 +++++----------------------------- docs/build.md | 69 ++++++++ docs/configuration.md | 11 ++ docs/deployment.md | 43 +++++ docs/features.md | 93 +++++++++++ docs/getting_started.md | 100 ++++++++++++ docs/security.md | 57 +++++++ images/authelia-title.png | Bin 0 -> 47989 bytes images/email_confirmation.png | Bin 26317 -> 35306 bytes images/first_factor.png | Bin 20857 -> 33496 bytes images/reset_password.png | Bin 25508 -> 39510 bytes images/second_factor.png | Bin 23759 -> 59063 bytes images/totp.png | Bin 27934 -> 59974 bytes images/u2f.png | Bin 22513 -> 39361 bytes 14 files changed, 412 insertions(+), 260 deletions(-) create mode 100644 docs/build.md create mode 100644 docs/configuration.md create mode 100644 docs/deployment.md create mode 100644 docs/features.md create mode 100644 docs/getting_started.md create mode 100644 docs/security.md create mode 100644 images/authelia-title.png diff --git a/README.md b/README.md index efc402bf0..1c9a1576a 100644 --- a/README.md +++ b/README.md @@ -1,290 +1,71 @@ -# Authelia +

+ +

[![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)][MIT License] [![Build](https://travis-ci.org/clems4ever/authelia.svg?branch=master)](https://travis-ci.org/clems4ever/authelia) - [![Gitter](https://img.shields.io/gitter/room/badges/shields.svg)](https://gitter.im/authelia/general?utm_source=share-link&utm_medium=link&utm_campaign=share-link) + [![Slack](https://img.shields.io/badge/chat-on--slack-green.svg?longCache=true&style=flat)](https://authelia.slack.com/messages/C3YBS84NL) -**Authelia** is an open-source authentication and authorization server. -Authelia brings 2-factor authentication and single sign-on to secure web -applications and ease authentication. It has been designed to be a companion -of any reverse proxy by helping it handle authentication and authorization -requests. +**Authelia** is an open-source authentication and authorization providing + 2-factor authentication and single sign-on (SSO) for your applications. +It acts as a companion of reverse proxies by handling authentication and +authorization requests. -**Authelia** can be installed on bare-metal using Docker or npm but can also -be deployed easily on a Kubernetes cluster and leverages ingress controller -and ingress configuration concepts to easily configure authentication and -authorization for specific services in your cluster by simply editing your -ingress configuration. +**Authelia** can be installed as a standalone service using Docker or NPM +but can also be deployed easily on Kubernetes. On the latest, one can +leverage ingress configuration to set up authentication and authorizations +for specific services in only few seconds. - -# Table of Contents -1. [Features summary](#features-summary) -2. [Deployment](#deployment) - 1. [With NPM](#with-npm) - 2. [With Docker](#with-docker) - 3. [With Kubernetes](#with-docker) -3. [Getting started](#getting-started) - 1. [Pre-requisites](#pre-requisites) - 2. [Run it!](#run-it) -4. [Features in details](#features-in-details) - 1. [First factor with LDAP and ACL](#first-factor-with-ldap-and-acl) - 2. [Second factor with TOTP](#second-factor-with-totp) - 3. [Second factor with U2F security keys](#second-factor-with-u2f-security-keys) - 4. [Password reset](#password-reset) - 5. [Access control](#access-control) - 6. [Single factor authentication](#single-factor-authentication) - 7. [Session management with Redis](#session-management-with-redis) -4. [Security](#security) -5. [Documentation](#documentation) - 1. [Authelia configuration](#authelia-configuration) - 2. [Wiki](#wiki) - 3. [API documentation](#api-documentation) -6. [Contributing to Authelia](#contributing-to-authelia) -7. [License](#license) - ---- +

+ + +

## Features summary -* Two-factor authentication using either -**[TOTP] - Time-Base One Time password -** or **[U2F] - Universal 2-Factor -** -as 2nd factor. + +Here is the list of the main available features: + +* **[U2F] - Universal 2-Factor -** support with [Yubikey]. +* **[TOTP] - Time-Base One Time password -** support with [Google Authenticator]. * Password reset with identity verification using email. -* Single and two factors authentication methods available. +* Single-factor only authentication method available. * Access restriction after too many authentication attempts. * User-defined access control per subdomain and resource. * Support of [basic authentication] for endpoints protected by single factor. -* High-availability using a highly-available distributed database and KV store. +* High-availability using distributed database and KV store. * Compatible with Kubernetes ingress-nginx controller out of the box. -## Deployment +For more details about the features, follow [Features](./docs/features.md). -If you don't have any LDAP and/or nginx setup yet, I advise you to follow the -[Getting Started](#Getting-started) section. That way, you can test it right away -without even configuring anything. +## Getting Started -Otherwise, 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. - -### 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 -v /path/to/data/dir:/var/lib/authelia clems4ever/authelia - -where **/path/to/data/dir** is the directory where all user data will be stored. - -### With Kubernetes - - - -Please refer to the following [README](./example/kube/README.md). - -## Getting started - -The provided example is docker-based so that you can deploy and test it very -quickly. - -### Pre-requisites - -#### npm -Make sure you have npm and node installed on your computer. - -#### Docker -Make sure you have **docker** and **docker-compose** installed on your machine. -For your information, here are the versions that have been used for testing: - - docker --version - -gave *Docker version 17.03.1-ce, build c6d412e*. - - docker-compose --version - -gave *docker-compose version 1.14.0, build c7bdf9e*. - -#### Available port -Make sure you don't have anything listening on port 8080 (webserver) and 8085 (webmail). - -#### Subdomain aliases - -Add the following lines to your **/etc/hosts** to alias multiple subdomains so that nginx can redirect request to the correct virtual host. - - 127.0.0.1 home.example.com - 127.0.0.1 public.example.com - 127.0.0.1 dev.example.com - 127.0.0.1 admin.example.com - 127.0.0.1 mx1.mail.example.com - 127.0.0.1 mx2.mail.example.com - 127.0.0.1 single_factor.example.com - 127.0.0.1 login.example.com - -### Run it! - -Deploy the **Authelia** example with one of the following commands: - -Build Docker container from current commit: - - ./scripts/build-dev.sh - ./scripts/example-commit/deploy-example.sh - -Use provided container on [DockerHub](https://hub.docker.com/r/clems4ever/authelia/): - - ./scripts/example-dockerhub/deploy-example.sh - -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 target page. The certificate -must also be trusted for each subdomain, therefore it is normal to see the exception - several times. - -Below is what the login page looks like: - - - -## Features in details - -### First factor using an 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 -corresponds to the first factor. Authelia tries to bind the username and password -against the configured LDAP backend. - -You can find an example of the configuration of the LDAP backend in [config.template.yml]. - - - - -### Second factor with TOTP -In **Authelia**, you can register a per user TOTP (Time-Based One Time Password) secret before -authenticating. To do that, you need to click on the register button. It will -send a link to the user email address stored in LDAP. Since this is an example, the email is sent -to a fake email address you can access from the webmail at [http://localhost:8085](http://localhost:8085). -Click on **Continue** and you'll get your secret in QRCode and Base32 formats. You can use -[Google Authenticator] -to store them and get the generated tokens with the app. - -**Note:** If you're testing with **npm**, you will not have access to the fake webmail. You can use the filesystem notifier (option available [config.template.yml]) that will create a file containing the validation URL instead of sending an email. Please only use it for testing. - - - -### Second factor with U2F security keys -**Authelia** also offers authentication using U2F (Universal 2-Factor) devices like [Yubikey](Yubikey) -USB security keys. U2F is one of the most secure authentication protocol and is -already available for Google, Facebook, Github accounts and more. - -Like TOTP, U2F requires you register your security key before authenticating. -To do so, click on the register button. This will send a link to the -user email address. Since this is an example, the email is sent -to a fake email address you can access from the webmail at [http://localhost:8085](http://localhost:8085). -Click on **Continue** and you'll be asking to touch the token of your device -to register. Upon successful registration, you can authenticate using your U2F -device by simply touching the token. Easy, right?! - -**Note:** If you're testing with **npm**, you will not have access to the fake webmail. You can use the filesystem notifier (option available [config.template.yml]) that will create a file containing the validation URL instead of sending an email. Please only use it for testing. - - - -### Password reset -With **Authelia**, you can also reset your password in no time. Click on the -**Forgot password?** link in the login page, provide the username of the user requiring -a password reset and **Authelia** will send an email with an link to the user -email address. For the sake of the example, the email is delivered in a fake webmail deployed -for you and accessible at [http://localhost:8085](http://localhost:8085). -Paste the link in your browser and you should be able to reset the password. - -**Note:** If you're testing with **npm**, you will not have access to the fake webmail. You can use the filesystem notifier (option available [config.template.yml]) that will create a file containing the validation URL instead of sending an email. Please only use it for testing. - - - -### Access Control -With **Authelia**, you can define your own access control rules for finely restricting -user access to some resources and subdomains. Those rules are defined and fully documented -in the configuration file. They can apply to users, groups or everyone. -Check out [config.template.yml] to see how they are defined. - -### Single factor authentication -Authelia allows you to customize the authentication method to use for each -sub-domain.The supported methods are either "single_factor" or "two_factor". -Please see [config.template.yml] to see an example of configuration. - -It is also possible to use [basic authentication] to access a resource -protected by a single factor. - -### Session management with Redis -When your users authenticate against Authelia, sessions are stored in a Redis key/value store. You can specify your own Redis instance in [config.template.yml]. +Follow [Getting Started](./docs/getting_started.md). ## Security -### Protection against cookie theft +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). -Authelia uses two mechanism 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 -unsecure HTTP connections. +## Deployment -### Protection against multi-domain cookie attacks +To learn how to deploy **Authelia** or use it on Kubernetes, please follow +[Deployment](./docs/deployment.md). -Since Authelia uses multi-domain cookies to perform single sign-on, an -attacker who poisonned a user's DNS cache can easily retrieve the user's -cookies by making the user send a request to one of the attacker's IPs. +## Build Authelia -To mitigate this risk, it's advisable to only use HTTPS connections with valid -certificates and enforce it with HTTP Strict Transport Security ([HSTS]) so -that the attacker must also require the certificate to retrieve the cookies. +Follow [Build](./docs/build.md). -Note that using [HSTS] has consequences. That's why you should read the blog -post nginx has written on [HSTS]. +## Changelog -### More protections measures +See [Changelog](CHANGELOG.md). -You can also apply the following headers to your nginx configuration for -improving security. Please read the documentation of those headers before -applying them blindly. +## Contributing -``` -# We don't want any credentials / TOTP secret key / QR code to be cached by -# the client -add_header Cache-Control "no-store"; -add_header Pragma "no-cache"; - -# Clickjacking / XSS protection - -# We don't want Authelia's login page to be rendered within a , -#