From 100d598a0edfef6980e2cbf2af554f4217d27497 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Michaud?= <clement.michaud34@gmail.com>
Date: Wed, 9 Feb 2022 23:10:35 +0100
Subject: [PATCH] docs: add documentation about the logout endpoint (#2860)

fix #2859
---
 docs/features/logout.md   | 51 +++++++++++++++++++++++++++++++++++++++
 docs/security/measures.md |  6 +++++
 2 files changed, 57 insertions(+)
 create mode 100644 docs/features/logout.md

diff --git a/docs/features/logout.md b/docs/features/logout.md
new file mode 100644
index 00000000..6f713777
--- /dev/null
+++ b/docs/features/logout.md
@@ -0,0 +1,51 @@
+---
+layout: default
+title: Logout
+parent: Features
+nav_order: 8
+---
+
+# Logout
+
+Authelia is able to log out your users to ensure their account is not exposed anymore when they stop
+surfing the web.
+
+When user is logged out, the cookie attached to this user is reset on the backend side. Therefore, any
+subsequent request using this old cookie is considered unauthenticated by Authelia. In this case the user
+is simply redirected to the login page and has to authenticate again to generate a new session with a new cookie.
+
+## Methods to log out
+
+## Frontend
+
+In most websites and applications, users can usually click on a logout button to be signed out and Authelia
+offers the same feature.
+
+Implementing logout is as easy as putting a link or button somewhere on your application or website with
+the following href: `https://auth.example.com/logout` where `auth.example.com` is the domain serving Authelia.
+By default, this would redirect the user to the login page of Authelia but one can force the redirection to any
+domain protected by Authelia by appending the 'rd' query parameter which should be set to the target URL where
+the user should be redirected. For instance, `https://auth.example.com/logout?rd=https://homepage.example.com`.
+
+Please note that an attempt of redirection to a domain which is not a subdomain protected by Authelia will be
+skipped for security reasons described later in this page.
+
+## Backend
+
+The backend API can also be called directly from your applications if needed. The endpoint is /api/logout which
+is taking a POST request with a body like:
+
+    {
+        "targetURL": "https://homepage.example.com"
+    }
+
+Please note that an attempt of redirection to a domain which is not a subdomain protected by Authelia will be
+skipped for security reasons described later in this page.
+
+## Why preventing redirection to some domains?
+
+This is a security feature which is protecting your users against attacks called open redirect. This kind of attack
+is described [here](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html)
+by the [OWASP](https://en.wikipedia.org/wiki/OWASP#:~:text=The%20Open%20Web%20Application%20Security,field%20of%20web%20application%20security.&text=It%20is%20led%20by%20a%20non%2Dprofit%20called%20The%20OWASP%20Foundation.).
+In a nutshell, hackers can send phishing emails to your users and trick them by making them click on a legit link
+eventually redirecting to an infected website.
\ No newline at end of file
diff --git a/docs/security/measures.md b/docs/security/measures.md
index aca32052..90ba7b19 100644
--- a/docs/security/measures.md
+++ b/docs/security/measures.md
@@ -183,6 +183,12 @@ connection is over TLS. As SMTPS is deprecated, the only way to configure this i
 to automatically consider it to be a SMTPS connection. As such your SMTP server, if not offering SMTPS, should not be
 listening on port 465 which is bad practice anyway.
 
+## Protection against open redirects
+
+Authelia protects your users against open redirect attacks by always checking if redirection URLs are pointing
+to a subdomain of the domain protected by Authelia. This prevents phishing campaigns tricking users into visiting
+infected websites leveraging legit links.
+
 ## Additional security
 
 ### Reset Password