Update documentation and changelog for redis store

CHANGELOG.md

@@ -14,6 +14,12 @@
 
 ## Changes since v3.2.0
 
+- [#155](https://github.com/pusher/outh2_proxy/pull/155) Add RedisSessionStore implementation (@brianv0, @JoelSpeed)
+  - Implement flags to configure the redis session store
+    -  `-redis-connection-url`
+  - Introduces the concept of a session ticket. Tickets are composed of the cookie name, a session ID, and a secret. 
+  - Sessions are stored encrypted with a per-session secret 
+  - Added Some tests for a Server based session store
 - [#168](https://github.com/pusher/outh2_proxy/pull/168) Drop Go 1.11 support in Travis (@JoelSpeed)
 - [#169](https://github.com/pusher/outh2_proxy/pull/169) Update Alpine to 3.9 (@kskewes)
 - [#148](https://github.com/pusher/outh2_proxy/pull/148) Implement SessionStore interface within proxy (@JoelSpeed)

docs/configuration/configuration.md

@@ -75,6 +75,7 @@ Usage of oauth2_proxy:
   -pubjwk-url string: JWK pubkey access endpoint: required by login.gov
   -redeem-url string: Token redemption endpoint
   -redirect-url string: the OAuth Redirect URL. ie: "https://internalapp.yourcompany.com/oauth2/callback"
+  -redis-connection-url string: URL of redis server for redis session storage type (eg: redis://HOST[:PORT])
   -request-logging: Log requests to stdout (default true)
   -request-logging-format: Template for request log lines (see "Logging Configuration" paragraph below)
   -resource string: The resource that is protected (Azure AD only)

docs/configuration/sessions.md

@@ -16,6 +16,7 @@ data in one of the available session storage backends.
 
 At present the available backends are (as passed to `--session-store-type`):
 - [cookie](cookie-storage) (default)
+- [redis](redis-storage)
 
 ### Cookie Storage
 
@@ -32,3 +33,26 @@ The following should be known when using this implementation:
 - 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
+
+
+### Redis Storage
+
+The Redis Storage backend stores sessions, encrypted, in redis. Instead sending all the information
+back the the client for storage, as in the [Cookie storage](cookie-storage), a ticket is sent back
+to the user as the cookie value instead.
+
+A ticket is composed as the following:
+
+`{CookieName}-{ticketID}.{secret}`
+
+Where:
+
+- The `CookieName` is the OAuth2 cookie name (_oauth2_proxy by default)
+- The `ticketID` is a 128 bit random number, hex-encoded
+- The `secret` is a 128 bit random number, base64url encoded (no padding). The secret is unique for every session.
+- The pair of `{CookieName}-{ticketID}` comprises a ticket handle, and thus, the redis key
+to which the session is stored. The encoded session is encrypted with the secret and stored
+in redis via the `SETEX` command.
+
+Encrypting every session uniquely protects the refresh/access/id tokens stored in the session from
+disclosure.

main.go

@@ -76,7 +76,7 @@ func main() {
 	flagSet.Bool("cookie-httponly", true, "set HttpOnly cookie flag")
 
 	flagSet.String("session-store-type", "cookie", "the session storage provider to use")
-	flagSet.String("redis-connection-url", "", "URL of redis server for redis session storage (eg: redis://HOST[:PORT])")
+	flagSet.String("redis-connection-url", "", "URL of redis server for redis session storage type (eg: redis://HOST[:PORT])")
 
 	flagSet.String("logging-filename", "", "File to log requests to, empty for stdout")
 	flagSet.Int("logging-max-size", 100, "Maximum size in megabytes of the log file before rotation")