diff --git a/docs/3_configuration.md b/docs/configuration/configuration.md similarity index 99% rename from docs/3_configuration.md rename to docs/configuration/configuration.md index b390944..fd33d37 100644 --- a/docs/3_configuration.md +++ b/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) diff --git a/docs/configuration/sessions.md b/docs/configuration/sessions.md new file mode 100644 index 0000000..1896a5d --- /dev/null +++ b/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