1
0
mirror of https://github.com/oauth2-proxy/oauth2-proxy.git synced 2025-04-21 12:17:22 +02:00

42 lines
21 KiB
HTML

<!doctype html>
<html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-7.5.x plugin-docs plugin-id-default docs-doc-id-configuration/session_storage">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v2.4.1">
<title data-rh="true">Session Storage | OAuth2 Proxy</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/session_storage"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="7.5.x"><meta data-rh="true" name="docusaurus_tag" content="docs-default-7.5.x"><meta data-rh="true" name="docsearch:version" content="7.5.x"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-7.5.x"><meta data-rh="true" property="og:title" content="Session Storage | OAuth2 Proxy"><meta data-rh="true" name="description" content="Sessions allow a user&#x27;s authentication to be tracked between multiple HTTP"><meta data-rh="true" property="og:description" content="Sessions allow a user&#x27;s authentication to be tracked between multiple HTTP"><link data-rh="true" rel="icon" href="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg"><link data-rh="true" rel="canonical" href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/session_storage"><link data-rh="true" rel="alternate" href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/session_storage" hreflang="en"><link data-rh="true" rel="alternate" href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/session_storage" hreflang="x-default"><link rel="stylesheet" href="/oauth2-proxy/assets/css/styles.5c990d8a.css">
<link rel="preload" href="/oauth2-proxy/assets/js/runtime~main.0abade7b.js" as="script">
<link rel="preload" href="/oauth2-proxy/assets/js/main.7f0e9d83.js" as="script">
</head>
<body class="navigation-with-keyboard">
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus">
<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/oauth2-proxy/"><div class="navbar__logo"><img src="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg" alt="OAuth2 Proxy" class="themedImage_ToTc themedImage--light_HNdA"><img src="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg" alt="OAuth2 Proxy" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">OAuth2 Proxy</b></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/oauth2-proxy/docs/">Docs</a></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class="navbar__link" aria-haspopup="true" aria-expanded="false" role="button" href="/oauth2-proxy/docs/">7.5.x</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/oauth2-proxy/docs/next/configuration/session_storage">Next</a></li><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/oauth2-proxy/docs/configuration/session_storage">7.5.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/7.4.x/configuration/session_storage">7.4.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/7.3.x/configuration/session_storage">7.3.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/7.2.x/configuration/session_storage">7.2.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/7.1.x/configuration/session_storage">7.1.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/7.0.x/configuration/session_storage">7.0.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/6.1.x/configuration/session_storage">6.1.x</a></li></ul></div><a href="https://github.com/oauth2-proxy/oauth2-proxy" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><div class="navbar__search searchBarContainer_NW3z"><input placeholder="Search" aria-label="Search" class="navbar__search-input"><div class="loadingRing_RJI3 searchBarLoadingRing_YnHq"><div></div><div></div><div></div><div></div></div><div class="searchHintContainer_Pkmr"><kbd class="searchHint_iIMx">ctrl</kbd><kbd class="searchHint_iIMx">K</kbd></div></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebarViewport_Xe31"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/oauth2-proxy/docs/">Installation</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/oauth2-proxy/docs/behaviour">Behaviour</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" aria-expanded="true" href="/oauth2-proxy/docs/configuration/overview">Configuration</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/configuration/overview">Overview</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/configuration/oauth_provider">OAuth Provider Configuration</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/oauth2-proxy/docs/configuration/session_storage">Session Storage</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/configuration/tls">TLS Configuration</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/configuration/alpha-config">Alpha Configuration</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="true" href="/oauth2-proxy/docs/features/endpoints">Features</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/features/endpoints">Endpoints</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="true" href="/oauth2-proxy/docs/community/security">Community</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/community/security">Security</a></li></ul></li></ul></nav></div></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/oauth2-proxy/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Configuration</span><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Session Storage</span><meta itemprop="position" content="2"></li></ul></nav><span class="theme-doc-version-badge badge badge--secondary">Version: 7.5.x</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Session Storage</h1></header><p>Sessions allow a user&#x27;s authentication to be tracked between multiple HTTP
requests to a service.</p><p>The OAuth2 Proxy uses a Cookie to track user sessions and will store the session
data in one of the available session storage backends.</p><p>At present the available backends are (as passed to <code>--session-store-type</code>):</p><ul><li><a href="#cookie-storage">cookie</a> (default)</li><li><a href="#redis-storage">redis</a></li></ul><h3 class="anchor anchorWithStickyNavbar_LWe7" id="cookie-storage">Cookie Storage<a href="#cookie-storage" class="hash-link" aria-label="Direct link to Cookie Storage" title="Direct link to Cookie Storage"></a></h3><p>The Cookie storage backend is the default backend implementation and has
been used in the OAuth2 Proxy historically.</p><p>With the Cookie storage backend, all session information is stored in client
side cookies and transferred with each and every request.</p><p>The following should be known when using this implementation:</p><ul><li>Since all state is stored client side, this storage backend means that the OAuth2 Proxy is completely stateless</li><li>Cookies are signed server side to prevent modification client-side</li><li>It is mandatory to set a <code>cookie-secret</code> which will ensure data is encrypted within the cookie data.</li><li>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</li></ul><h3 class="anchor anchorWithStickyNavbar_LWe7" id="redis-storage">Redis Storage<a href="#redis-storage" class="hash-link" aria-label="Direct link to Redis Storage" title="Direct link to Redis Storage"></a></h3><p>The Redis Storage backend stores sessions, encrypted, in redis. Instead sending all the information
back the client for storage, as in the <a href="#cookie-storage">Cookie storage</a>, a ticket is sent back
to the user as the cookie value instead.</p><p>A ticket is composed as the following:</p><p><code>{CookieName}-{ticketID}.{secret}</code></p><p>Where:</p><ul><li>The <code>CookieName</code> is the OAuth2 cookie name (_oauth2_proxy by default)</li><li>The <code>ticketID</code> is a 128 bit random number, hex-encoded</li><li>The <code>secret</code> is a 128 bit random number, base64url encoded (no padding). The secret is unique for every session.</li><li>The pair of <code>{CookieName}-{ticketID}</code> 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 <code>SETEX</code> command.</li></ul><p>Encrypting every session uniquely protects the refresh/access/id tokens stored in the session from
disclosure.</p><p>Additionally the browser only has to send a short Cookie with every request and not the whole JWT, which can get quite big.</p><p>Two settings are used to configure the OAuth2 Proxy cookie lifetime:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">--cookie-refresh duration refresh the cookie after this duration; 0 to disable</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--cookie-expire duration expire timeframe for cookie 168h0m0s</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>The &quot;cookie-expire&quot; 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.</p><p>The &quot;cookie-refresh&quot; value controls when OAuth2 Proxy tries to refresh an Access-Token. If it is set to &quot;0&quot;, 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.</p><p>Caveat: It can happen that the Access-Token is valid for e.g. &quot;1m&quot; and a request happens after exactly &quot;59s&quot;.
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&#x27;s advised to set the cookie-refresh a couple of seconds less than the Access-Token lifespan.</p><p>Recommended settings:</p><ul><li>cookie<!-- -->_<!-- -->refresh := Access-Token lifespan - 1m</li><li>cookie<!-- -->_<!-- -->expire := Refresh-Token lifespan (i.e. Keycloak&#x27;s client<!-- -->_<!-- -->session<!-- -->_<!-- -->idle)</li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="usage">Usage<a href="#usage" class="hash-link" aria-label="Direct link to Usage" title="Direct link to Usage"></a></h4><p>When using the redis store, specify <code>--session-store-type=redis</code> as well as the Redis connection URL, via
<code>--redis-connection-url=redis://host[:port][/db-number]</code>.</p><p>You may also configure the store for Redis Sentinel. In this case, you will want to use the
<code>--redis-use-sentinel=true</code> flag, as well as configure the flags <code>--redis-sentinel-master-name</code>
and <code>--redis-sentinel-connection-urls</code> appropriately.</p><p>Redis Cluster is available to be the backend store as well. To leverage it, you will need to set the
<code>--redis-use-cluster=true</code> flag, and configure the flags <code>--redis-cluster-connection-urls</code> appropriately.</p><p>Note that flags <code>--redis-use-sentinel=true</code> and <code>--redis-use-cluster=true</code> are mutually exclusive.</p><p>Note, if Redis timeout option is set to non-zero, the <code>--redis-connection-idle-timeout</code>
must be less than <a href="https://redis.io/docs/reference/clients/#client-timeouts" target="_blank" rel="noopener noreferrer">Redis timeout option</a>. For example: if either redis.conf includes
<code>timeout 15</code> or using <code>CONFIG SET timeout 15</code> the <code>--redis-connection-idle-timeout</code> must be at least <code>--redis-connection-idle-timeout=14</code></p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/oauth2-proxy/oauth2-proxy/edit/master/docs/versioned_docs/version-7.5.x/configuration/sessions.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/oauth2-proxy/docs/configuration/oauth_provider"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">OAuth Provider Configuration</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/oauth2-proxy/docs/configuration/tls"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">TLS Configuration</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#cookie-storage" class="table-of-contents__link toc-highlight">Cookie Storage</a></li><li><a href="#redis-storage" class="table-of-contents__link toc-highlight">Redis Storage</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2023 OAuth2 Proxy.</div></div></div></footer></div>
<script src="/oauth2-proxy/assets/js/runtime~main.0abade7b.js"></script>
<script src="/oauth2-proxy/assets/js/main.7f0e9d83.js"></script>
</body>
</html>