go/oauth2-proxy
1
0
Fork 0
mirror of https://github.com/oauth2-proxy/oauth2-proxy.git synced 2024-11-24 08:52:25 +02:00
Code Issues Releases Activity

Improved session documentation (#2208)

Browse Source 
* Improved session documentation

* Replaced "OAuth2-Proxy" with "OAuth2 Proxy"
This commit is contained in:
Christian Brunotte 2023-09-08 10:51:18 +02:00 committed by GitHub
parent 9f06dc873c
commit 5f2f95e118
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 28 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/docs/configuration/sessions.md
View File

@ -52,6 +52,33 @@ in redis via the `SETEX` command.
Encrypting every session uniquely protects the refresh/access/id tokens stored in the session from Encrypting every session uniquely protects the refresh/access/id tokens stored in the session from
disclosure. disclosure.
Additionally the browser only has to send a short Cookie with every request and not the whole JWT, which can get quite big.
Two settings are used to configure the OAuth2 Proxy cookie lifetime:
--cookie-refresh duration refresh the cookie after this duration; 0 to disable
--cookie-expire duration expire timeframe for cookie 168h0m0s
The "cookie-expire" value should be equal to the lifetime of the Refresh-Token that is issued by the OAuth2 authorization server.
If it expires earlier and is deleted by the browser, OAuth2 Proxy cannot find the stored Refresh-Tokens in Redis and thus cannot start
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
expired.
The "cookie-refresh" value controls when OAuth2 Proxy tries to refresh an Access-Token. If it is set to "0", the
Access-Token will never be refreshed, even it is already expired and there would be a valid Refresh-Token in the
available. If set, OAuth2 Proxy will refresh the Access-Token after this many seconds even if it is still valid.
Of course, it will also be refreshed after it has expired, as long as a Refresh Token is available.
Caveat: It can happen that the Access-Token is valid for e.g. "1m" and a request happens after exactly "59s".
It would pass OAuth2 Proxy and be forwarded to the backend but is just expired when the backend tries to validate
it. This is especially relevant if the backend uses the JWT to make requests to other backends.
For this reason, it's advised to set the cookie-refresh a couple of seconds less than the Access-Token lifespan.
Recommended settings:
* cookie\_refresh := Access-Token lifespan - 1m
* cookie\_expire := Refresh-Token lifespan (i.e. Keycloak's client\_session\_idle)
#### Usage #### Usage
When using the redis store, specify `--session-store-type=redis` as well as the Redis connection URL, via When 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
Note, if Redis timeout option is set to non-zero, the `--redis-connection-idle-timeout` Note, if Redis timeout option is set to non-zero, the `--redis-connection-idle-timeout`
must be less than [Redis timeout option](https://redis.io/docs/reference/clients/#client-timeouts). For example: if either redis.conf includes must be less than [Redis timeout option](https://redis.io/docs/reference/clients/#client-timeouts). For example: if either redis.conf includes
`timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14` `timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14`