Update documentation to include session storage

docs/configuration/configuration.md

@@ -1,7 +1,8 @@
 ---
 layout: default
 title: Configuration
-permalink: /configuration
+permalink: /docs/configuration
+has_children: true
 nav_order: 3
 ---
 
@@ -78,6 +79,7 @@ Usage of oauth2_proxy:
   -request-logging-format: Template for request log lines (see "Logging Configuration" paragraph below)
   -resource string: The resource that is protected (Azure AD only)
   -scope string: OAuth scope specification
+  -session-store-type: Session data storage backend (default: cookie)
   -set-xauthrequest: set X-Auth-Request-User and X-Auth-Request-Email response headers (useful in Nginx auth_request mode)
   -set-authorization-header: set Authorization Bearer response header (useful in Nginx auth_request mode)
   -signature-key string: GAP-Signature request signature key (algorithm:secretkey)

docs/configuration/sessions.md

@@ -0,0 +1,34 @@
+---
+layout: default
+title: Sessions
+permalink: /configuration
+parent: Configuration
+nav_order: 3
+---
+
+## Sessions
+
+Sessions allow a user's authentication to be tracked between multiple HTTP
+requests to a service.
+
+The OAuth2 Proxy uses a Cookie to track user sessions and will store the session
+data in one of the available session storage backends.
+
+At present the available backends are (as passed to `--session-store-type`):
+- [cookie](cookie-storage) (deafult)
+
+### Cookie Storage
+
+The Cookie storage backend is the default backend implementation and has
+been used in the OAuth2 Proxy historically.
+
+With the Cookie storage backend, all session information is stored in client
+side cookies and transferred with each and every request.
+
+The following should be known when using this implementation:
+- Since all state is stored client side, this storage backend means that the OAuth2 Proxy is completely stateless
+- Cookies are signed server side to prevent modification client-side
+- It is recommended to set a `cookie-secret` which will ensure data is encrypted within the cookie data.
+- Since multiple requests can be made concurrently to the OAuth2 Proxy, this session implementation
+cannot lock sessions and while updating and refreshing sessions, there can be conflicts which force
+users to re-authenticate