"use strict";(self.webpackChunkdocusaurus=self.webpackChunkdocusaurus||[]).push([[1898],{3905:function(e,t,n){n.d(t,{Zo:function(){return c},kt:function(){return h}});var r=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function s(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?o(Object(n),!0).forEach((function(t){i(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):o(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function a(e,t){if(null==e)return{};var n,r,i=function(e,t){if(null==e)return{};var n,r,i={},o=Object.keys(e);for(r=0;r<o.length;r++)n=o[r],t.indexOf(n)>=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r<o.length;r++)n=o[r],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var l=r.createContext({}),u=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},c=function(e){var t=u(e.components);return r.createElement(l.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},p=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,c=a(e,["components","mdxType","originalType","parentName"]),p=u(n),h=i,k=p["".concat(l,".").concat(h)]||p[h]||d[h]||o;return n?r.createElement(k,s(s({ref:t},c),{},{components:n})):r.createElement(k,s({ref:t},c))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,s=new Array(o);s[0]=p;var a={};for(var l in t)hasOwnProperty.call(t,l)&&(a[l]=t[l]);a.originalType=e,a.mdxType="string"==typeof e?e:i,s[1]=a;for(var u=2;u<o;u++)s[u]=n[u];return r.createElement.apply(null,s)}return r.createElement.apply(null,n)}p.displayName="MDXCreateElement"},6485:function(e,t,n){n.r(t),n.d(t,{frontMatter:function(){return a},contentTitle:function(){return l},metadata:function(){return u},toc:function(){return c},default:function(){return p}});var r=n(7462),i=n(3366),o=(n(7294),n(3905)),s=["components"],a={id:"session_storage",title:"Session Storage"},l=void 0,u={unversionedId:"configuration/session_storage",id:"version-7.1.x/configuration/session_storage",title:"Session Storage",description:"Sessions allow a user's authentication to be tracked between multiple HTTP",source:"@site/versioned_docs/version-7.1.x/configuration/sessions.md",sourceDirName:"configuration",slug:"/configuration/session_storage",permalink:"/oauth2-proxy/docs/7.1.x/configuration/session_storage",editUrl:"https://github.com/oauth2-proxy/oauth2-proxy/edit/master/docs/versioned_docs/version-7.1.x/configuration/sessions.md",tags:[],version:"7.1.x",frontMatter:{id:"session_storage",title:"Session Storage"},sidebar:"version-7.1.x/docs",previous:{title:"OAuth Provider Configuration",permalink:"/oauth2-proxy/docs/7.1.x/configuration/oauth_provider"},next:{title:"TLS Configuration",permalink:"/oauth2-proxy/docs/7.1.x/configuration/tls"}},c=[{value:"Cookie Storage",id:"cookie-storage",children:[],level:3},{value:"Redis Storage",id:"redis-storage",children:[{value:"Usage",id:"usage",children:[],level:4}],level:3}],d={toc:c};function p(e){var t=e.components,n=(0,i.Z)(e,s);return(0,o.kt)("wrapper",(0,r.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Sessions allow a user's authentication to be tracked between multiple HTTP\nrequests to a service."),(0,o.kt)("p",null,"The OAuth2 Proxy uses a Cookie to track user sessions and will store the session\ndata in one of the available session storage backends."),(0,o.kt)("p",null,"At present the available backends are (as passed to ",(0,o.kt)("inlineCode",{parentName:"p"},"--session-store-type"),"):"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"#cookie-storage"},"cookie")," (default)"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"#redis-storage"},"redis"))),(0,o.kt)("h3",{id:"cookie-storage"},"Cookie Storage"),(0,o.kt)("p",null,"The Cookie storage backend is the default backend implementation and has\nbeen used in the OAuth2 Proxy historically."),(0,o.kt)("p",null,"With the Cookie storage backend, all session information is stored in client\nside cookies and transferred with each and every request."),(0,o.kt)("p",null,"The following should be known when using this implementation:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Since all state is stored client side, this storage backend means that the OAuth2 Proxy is completely stateless"),(0,o.kt)("li",{parentName:"ul"},"Cookies are signed server side to prevent modification client-side"),(0,o.kt)("li",{parentName:"ul"},"It is mandatory to set a ",(0,o.kt)("inlineCode",{parentName:"li"},"cookie-secret")," which will ensure data is encrypted within the cookie data."),(0,o.kt)("li",{parentName:"ul"},"Since multiple requests can be made concurrently to the OAuth2 Proxy, this session implementation\ncannot lock sessions and while updating and refreshing sessions, there can be conflicts which force\nusers to re-authenticate")),(0,o.kt)("h3",{id:"redis-storage"},"Redis Storage"),(0,o.kt)("p",null,"The Redis Storage backend stores sessions, encrypted, in redis. Instead sending all the information\nback the client for storage, as in the ",(0,o.kt)("a",{parentName:"p",href:"#cookie-storage"},"Cookie storage"),", a ticket is sent back\nto the user as the cookie value instead."),(0,o.kt)("p",null,"A ticket is composed as the following:"),(0,o.kt)("p",null,(0,o.kt)("inlineCode",{parentName:"p"},"{CookieName}-{ticketID}.{secret}")),(0,o.kt)("p",null,"Where:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"The ",(0,o.kt)("inlineCode",{parentName:"li"},"CookieName")," is the OAuth2 cookie name (_oauth2_proxy by default)"),(0,o.kt)("li",{parentName:"ul"},"The ",(0,o.kt)("inlineCode",{parentName:"li"},"ticketID")," is a 128 bit random number, hex-encoded"),(0,o.kt)("li",{parentName:"ul"},"The ",(0,o.kt)("inlineCode",{parentName:"li"},"secret")," is a 128 bit random number, base64url encoded (no padding). The secret is unique for every session."),(0,o.kt)("li",{parentName:"ul"},"The pair of ",(0,o.kt)("inlineCode",{parentName:"li"},"{CookieName}-{ticketID}")," comprises a ticket handle, and thus, the redis key\nto which the session is stored. The encoded session is encrypted with the secret and stored\nin redis via the ",(0,o.kt)("inlineCode",{parentName:"li"},"SETEX")," command.")),(0,o.kt)("p",null,"Encrypting every session uniquely protects the refresh/access/id tokens stored in the session from\ndisclosure."),(0,o.kt)("h4",{id:"usage"},"Usage"),(0,o.kt)("p",null,"When using the redis store, specify ",(0,o.kt)("inlineCode",{parentName:"p"},"--session-store-type=redis")," as well as the Redis connection URL, via\n",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-connection-url=redis://host[:port][/db-number]"),"."),(0,o.kt)("p",null,"You may also configure the store for Redis Sentinel. In this case, you will want to use the\n",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-use-sentinel=true")," flag, as well as configure the flags ",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-sentinel-master-name"),"\nand ",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-sentinel-connection-urls")," appropriately."),(0,o.kt)("p",null,"Redis Cluster is available to be the backend store as well. To leverage it, you will need to set the\n",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-use-cluster=true")," flag, and configure the flags ",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-cluster-connection-urls")," appropriately."),(0,o.kt)("p",null,"Note that flags ",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-use-sentinel=true")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"--redis-use-cluster=true")," are mutually exclusive."))}p.isMDXComponent=!0}}]);