@@ -52,6 +52,33 @@ in redis via the `SETEX` command.
5252Encrypting every session uniquely protects the refresh/access/id tokens stored in the session from
5353disclosure.
5454
55+Additionally the browser only has to send a short Cookie with every request and not the whole JWT, which can get quite big.
56+
57+Two settings are used to configure the OAuth2 Proxy cookie lifetime:
58+
59+ --cookie-refresh duration refresh the cookie after this duration; 0 to disable
60+ --cookie-expire duration expire timeframe for cookie 168h0m0s
61+
62+The "cookie-expire" value should be equal to the lifetime of the Refresh-Token that is issued by the OAuth2 authorization server.
63+If it expires earlier and is deleted by the browser, OAuth2 Proxy cannot find the stored Refresh-Tokens in Redis and thus cannot start
64+the refresh flow to get new Access-Tokens. If it is longer, it might be that the old Refresh-Token will be found in Redis but has already
65+expired.
66+
67+The "cookie-refresh" value controls when OAuth2 Proxy tries to refresh an Access-Token. If it is set to "0", the
68+Access-Token will never be refreshed, even it is already expired and there would be a valid Refresh-Token in the
69+available. If set, OAuth2 Proxy will refresh the Access-Token after this many seconds even if it is still valid.
70+Of course, it will also be refreshed after it has expired, as long as a Refresh Token is available.
71+
72+Caveat: It can happen that the Access-Token is valid for e.g. "1m" and a request happens after exactly "59s".
73+It would pass OAuth2 Proxy and be forwarded to the backend but is just expired when the backend tries to validate
74+it. This is especially relevant if the backend uses the JWT to make requests to other backends.
75+For this reason, it's advised to set the cookie-refresh a couple of seconds less than the Access-Token lifespan.
76+
77+Recommended settings:
78+
79+* cookie\_refresh := Access-Token lifespan - 1m
80+* cookie\_expire := Refresh-Token lifespan (i.e. Keycloak's client\_session\_idle)
81+
5582#### Usage
5683
5784When using the redis store, specify `--session-store-type=redis` as well as the Redis connection URL, via
@@ -68,4 +95,4 @@ Note that flags `--redis-use-sentinel=true` and `--redis-use-cluster=true` are m
6895
6996Note, if Redis timeout option is set to non-zero, the `--redis-connection-idle-timeout`
7097must be less than [Redis timeout option](https://redis.io/docs/reference/clients/#client-timeouts). For example: if either redis.conf includes
71−`timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14`
98+`timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14`