{"type":"doc","content":[{"type":"paragraph","content":[{"text":"File(s):","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"conf/global.xml, conf/idp.properties","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Format:","type":"text","marks":[{"type":"strong"}]},{"text":" Native Spring","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"maxLevel":{"value":"2"}},"macroMetadata":{"macroId":{"value":"6d5217e6-90e3-45c1-b334-7d5143c6964e"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"4191158f-61db-4519-8031-790081774840"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"The IdP provides a number of general-purpose storage facilities that can be used by core subsystems like session management and consent. Broadly speaking, there are two kinds of storage plugins: client-side and server-side. Client-side plugins have the advantage of requiring no additional software or configuration and make clustering very robust and simple, but they only support a subset of use cases. Server-side plugins (aside from the simple case of storing data in memory) support all use cases, but require additional software and configuration, and usually create additional points of failure in a clustered deployment.","type":"text"}]},{"type":"paragraph","content":[{"text":"You may wish to review the ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1284276231"}},{"text":" topic, as it may have implications for your storage options and/or the need to address SameSite based on your chosen options.","type":"text"}]},{"type":"paragraph","content":[{"text":"The IdP ships with 3 preconfigured ","type":"text"},{"text":"org.opensaml.storage.StorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.StorageService"}}]},{"text":" beans:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"shibboleth.ClientSessionStorageService","type":"text","marks":[{"type":"strong"}]},{"text":" (of type ","type":"text"},{"text":"ClientStorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.impl.client.ClientStorageService"}}]},{"text":")","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Stores data in a browser session cookie or HTML local storage","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"shibboleth.ClientPersistentStorageService","type":"text","marks":[{"type":"strong"}]},{"text":" (of type ","type":"text"},{"text":"ClientStorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.impl.client.ClientStorageService"}}]},{"text":")","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Stores data in a long-lived browser cookie or HTML local storage","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"shibboleth.StorageService","type":"text","marks":[{"type":"strong"}]},{"text":" (of type ","type":"text"},{"text":"MemoryStorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/storage/impl/MemoryStorageService"}}]},{"text":")","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Stores data in server memory, does not survive restarts and is not replicated across a cluster","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"There are additional storage service plugins included in the software (JPA, memcached) but they are not predefined. Using them requires defining beans yourself and setting various properties to point to them.","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, the ","type":"text"},{"text":"shibboleth.ClientSessionStorageService","type":"text","marks":[{"type":"strong"}]},{"text":" bean, which stores data in the client, is used to store IdP session data, but that can be modified via the ","type":"text"},{"text":"idp.properties","type":"text","marks":[{"type":"em"}]},{"text":" file:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example changing IdP session storage","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"idp.session.StorageService = shibboleth.StorageService","type":"text"}]},{"type":"paragraph","content":[{"text":"There are additional properties that can be used to change how other data is stored on a per-use case basis, but note that some components can't rely on client-side storage options, and more specific documentation should address that.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference","type":"text"}]},{"type":"expand","attrs":{"title":"Properties"},"content":[{"type":"table","attrs":{"layout":"full-width","localId":"1e54f22c-cce6-4c7e-8a51-17d4d597d478"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"Property","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.storage.cleanupInterval","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Duration","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"PT10M","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Interval of background thread sweeping server-side storage for expired records","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.storage.htmlLocalStorage","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Boolean","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"false","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Whether to use HTML Local Storage (if available) instead of cookies","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.storage.clientSessionStorageName","type":"text"},{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"String","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"shib_idp_session_ss","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Name of cookie or HTML storage key used by the default per-session instance of the client storage service","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.storage.clientPersistentStorageName","type":"text"},{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"String","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"shib_idp_persistent_ss","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Name of cookie or HTML storage key used by the default persistent instance of the client storage service","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.session.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Bean ID of a ","type":"text"},{"text":"StorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.StorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.ClientSessionStorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Storage back-end to use for IdP sessions, authentication results, and optionally tracking of SP usage for logout","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.consent.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Bean ID of a ","type":"text"},{"text":"StorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.StorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.ClientPersistentStorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Storage back-end to use for consent and terms-of-use records","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.replayCache.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Bean ID of a ","type":"text"},{"text":"StorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.StorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Storage back-end to use for message replay checking (must be server-side)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.replayCache.strict","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Boolean","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"true","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Whether storage errors during replay checks should be treated as a replay","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.artifact.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Bean ID of a ","type":"text"},{"text":"StorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.StorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Storage back-end to use for short-lived SAML Artifact mappings (must be server-side)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[187.0]},"content":[{"type":"paragraph","content":[{"text":"idp.cas.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[77.0]},"content":[{"type":"paragraph","content":[{"text":"Bean ID of a ","type":"text"},{"text":"StorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.StorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Storage back-end to use for CAS ticket mappings (must be server-side)","type":"text"}]}]}]}]}]},{"type":"expand","attrs":{"title":"Beans"},"content":[{"type":"paragraph","content":[{"text":"The following beans (most of which are internal to the system) can be used in various properties to control what storage instances are used for specific purposes. You can define your own beans also (e.g. in ","type":"text"},{"text":"global.xml","type":"text","marks":[{"type":"em"}]},{"text":").","type":"text"}]},{"type":"table","attrs":{"layout":"wide","localId":"f891f9fe-c5ec-486b-bf7e-5119ddaff8a9"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[190.0]},"content":[{"type":"paragraph","content":[{"text":"Bean ID","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[112.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[428.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[190.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.StorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[112.0]},"content":[{"type":"paragraph","content":[{"text":"MemoryStorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/storage/impl/MemoryStorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[428.0]},"content":[{"type":"paragraph","content":[{"text":"Default server-side storage, stores data in memory","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[190.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.ClientSessionStorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[112.0]},"content":[{"type":"paragraph","content":[{"text":"ClientStorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.impl.client.ClientStorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[428.0]},"content":[{"type":"paragraph","content":[{"text":"Default client-side storage for per-session data, stores data in session cookies or HTML local storage","type":"text"},{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[190.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.ClientPersistentStorageService","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[112.0]},"content":[{"type":"paragraph","content":[{"text":"ClientStorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.impl.client.ClientStorageService"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[428.0]},"content":[{"type":"paragraph","content":[{"text":"Default client-side storage for long-lived data, stores data in persistent cookies or HTML local storage","type":"text"},{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[190.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.ClientStorageServices","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[112.0]},"content":[{"type":"paragraph","content":[{"text":"List<","type":"text"},{"text":"StorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.StorageService"}}]},{"text":">","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[428.0]},"content":[{"type":"paragraph","content":[{"text":"Enumeration of ","type":"text"},{"text":"ClientStorageService","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.storage.impl.client.ClientStorageService"}}]},{"text":" plugins used, ensures proper load/save of data","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Storage Implementations","type":"text"}]},{"type":"paragraph","content":[{"text":"There are three functionally-complete implementations of the storage interface supplied with the software.","type":"text"}]},{"type":"expand","attrs":{"title":"ClientStorageService "},"content":[{"type":"paragraph","content":[{"text":"The ClientStorageService is an advanced, and highly recommended, option that includes support for HTML Local Storage along with cookies as a fallback or alternative.","type":"text"}]},{"type":"paragraph","content":[{"text":"Local Storage support is enabled by default for new installation, but note that it requires JavaScript be enabled, because reading and writing to the client requires an explicit page be rendered. When JavaScript is enabled, the additional page appears quickly as a short-lived interstitial with a message about the loading or saving of the data to the client. In practice, it is has no material impact on the user experience.","type":"text"}]},{"type":"paragraph","content":[{"text":"Controlling this feature is handled by the ","type":"text"},{"text":"idp.storage.htmlLocalStorage","type":"text","marks":[{"type":"strong"}]},{"text":" property.","type":"text"}]},{"type":"paragraph","content":[{"text":"No configuration is required, but you may want to change the look and feel of the templates that are displayed to the client while data is being read or written. These pages don't require any user interaction as long as JavaScript is enabled, but they tend to be visible at least briefly, particularly the first time through. They're somewhat similar to the templates displayed when SAML messages are handed off to the browser.","type":"text"}]},{"type":"paragraph","content":[{"text":"Much of that look is obviously controlled by style sheets and message properties, but the \"visible\" portions are in ","type":"text"},{"text":"views/client-storage","type":"text","marks":[{"type":"em"}]},{"text":" (to avoid losing your changes on upgrades).","type":"text"}]},{"type":"paragraph","content":[{"text":"As to ","type":"text"},{"text":"why","type":"text","marks":[{"type":"strong"}]},{"text":" you would use Local Storage, there are really two main reasons:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Logout","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Consent","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The main reason for this feature is to enable the IdP's session manager to track and index the sessions created with SPs, and that information does not fit reliably in a cookie. That makes the single-logout feature unusable with client-side sessions unless Local Storage is enabled, since the IdP doesn't know what SPs to communicate with. Enabling the Local Storage feature is necessary but not sufficient to allow at least some form of single logout to work without moving session storage to the server. You also will need to ensure a couple of additional session management properties ","type":"text"},{"text":"(idp.session.trackSPSessions","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"idp.session.secondaryServiceIndex)","type":"text","marks":[{"type":"strong"}]},{"text":" are enabled, and they are also on by default in new installs. There are two properties because the latter is more a SAML-specific need that may not extend to other protocols in the future.","type":"text"}]},{"type":"paragraph","content":[{"text":"The consent feature is very limited when cookies are used because the number of records it can store is extremely small. If Local Storage is available, that limit is essentially ignored. If you're comfortable with tracking consent per-device, this is a much more practical way to deploy it at most sites than with a database. Of course, many deployers are not comfortable with per-device consent, but those same deployers may become a lot more comfortable with it after enough database connection failures due to the nearly universally poor quality of JDBC networking code.","type":"text"}]}]},{"type":"expand","attrs":{"title":"JPAStorageService"},"content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"JPA","type":"text","marks":[{"type":"link","attrs":{"href":"http://en.wikipedia.org/wiki/Java_Persistence_API"}}]},{"text":" storage facility uses ","type":"text"},{"text":"Hibernate ORM","type":"text","marks":[{"type":"link","attrs":{"href":"http://hibernate.org/orm/"}}]},{"text":" for searching and persistence using a relational database for storage. Example schemas are shown below.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Whatever you do, you MUST ensure the context and id columns are case-sensitively handled and compared. That is a requirement of the API that will be using the database. This is frequently NOT the default behavior of databases such as MySQL.","type":"text"}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"MySQL","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"sql"},"content":[{"text":"CREATE TABLE `StorageRecords` (\n `context` varchar(255) NOT NULL,\n `id` varchar(255) NOT NULL,\n `expires` bigint(20) DEFAULT NULL,\n `value` longtext NOT NULL,\n `version` bigint(20) NOT NULL,\n PRIMARY KEY (`context`,`id`)\n)","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"PostgreSQL or H2","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"sql"},"content":[{"text":"CREATE TABLE storagerecords (\n context varchar(255) NOT NULL,\n id varchar(255) NOT NULL,\n expires bigint DEFAULT NULL,\n value text NOT NULL,\n version bigint NOT NULL,\n PRIMARY KEY (context, id)\n);","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Oracle","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"sql"},"content":[{"text":"CREATE TABLE storagerecords (\n context varchar2(255) NOT NULL,\n id varchar2(255) NOT NULL,\n expires number(19,0),\n value clob NOT NULL,\n version number(19,0) NOT NULL,\n PRIMARY KEY (context, id)\n);","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to configure this service you must provide Spring bean configuration for the JPAStorageService that includes the driver, URL, and credentials for your database. You are required to provide a jar containing the driver for your particular database. In addition, we recommend the use of a DataSource that provides connection pooling, which may require installing an additional library as well.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following libraries provide connection pooling functionality:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Commons DBCP","type":"text","marks":[{"type":"link","attrs":{"href":"http://commons.apache.org/proper/commons-dbcp/"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tomcat JDBC Pool","type":"text","marks":[{"type":"link","attrs":{"href":"http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"BoneCP","type":"text","marks":[{"type":"link","attrs":{"href":"http://jolbox.com/"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HikariCP","type":"text","marks":[{"type":"link","attrs":{"href":"http://brettwooldridge.github.io/HikariCP/"}}]}]}]}]},{"type":"paragraph","content":[{"text":"In the DB-specific examples below use of HikariCP is demonstrated (","type":"text"},{"text":"class=\"com.zaxxer.hikari.HikariDataSource\", p:jdbcUrl=\"...\"","type":"text","marks":[{"type":"code"}]},{"text":" in the DataSource bean). When using other Connection Pool implementations change the class and properties appropriately, e.g.:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Apache Commons:","type":"text"},{"text":" class=\"org.apache.commons.dbcp.BasicDataSource\", p:url=\"...\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tomcat DBCP2: ","type":"text"},{"text":"class=\"org.apache.tomcat.dbcp.dbcp2.BasicDataSource\", p:url=\"...\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tomcat JDBC Pool: ","type":"text"},{"text":"class=\"org.apache.tomcat.jdbc.pool.DataSource\", p:url=\"...\"","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Installation","type":"text"}]},{"type":"paragraph","content":[{"text":"Place the driver jar and connection pooling jar in ","type":"text"},{"text":"edit-webapp/WEB-INF/lib","type":"text","marks":[{"type":"strong"}]},{"text":" then execute ","type":"text"},{"text":"bin/build.sh","type":"text","marks":[{"type":"em"}]},{"text":" or ","type":"text"},{"text":"bin/build.bat","type":"text","marks":[{"type":"em"}]},{"text":" as appropriate for your environment.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following configuration should be placed in ","type":"text"},{"text":"conf/global.xml","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"DB-independent Configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n \n \n \n \n \n \n \n \n","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"The specific examples that follow should NOT be assumed to be functional, as they likely are the product of different sources, varying amounts of testing (including none), and may not be current. Drivers get updated frequently and JDBC and database bugs appear and disappear with regularity. When in doubt, always grab new ones when problems appear.","type":"text"}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Postgres Configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n \n \n","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"MySQL Configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n \n","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Oracle Configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n \n","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"H2 Configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n \n \n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Further Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"LocalContainerEntityManagerFactoryBean","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/orm/jpa/LocalContainerEntityManagerFactoryBean.html"}}]},{"text":" contains more configuration options and is designed to eliminate the need for a persistence.xml file. If you need to alter the database schema you can deploy a custom mapping file which overrides column names and types.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"ORM Mapping","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n org.opensaml.storage.impl\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n ","type":"text"}]},{"type":"paragraph","content":[{"text":"Place your custom orm.xml file in ","type":"text"},{"text":"edit-webapp/WEB-INF/classes/META-INF/orm.xml","type":"text","marks":[{"type":"em"}]},{"text":" then rebuild your war. While you can configure a custom name and path for this file it ","type":"text"},{"text":"must","type":"text","marks":[{"type":"strong"}]},{"text":" be located on your web application classpath. File system paths are not supported.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Postgres LOB Concerns","type":"text"}]},{"type":"paragraph","content":[{"text":"Switch","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.switch.ch/"}}]},{"text":" identified an issue with the Postgres JDBC driver and the storage of LOBs related to the default mapping. Deployers can experience data loss when the Postgres vacuumlo command is run. It is recommend that a custom orm.xml file be used to override the value type:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Postgres ORM","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\norg.opensaml.storage.impl\n\n \n \n \n \n \n\n","type":"text"}]},{"type":"paragraph","content":[{"text":"See the ","type":"text"},{"text":"Switch Installation Docs","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.switch.ch/aai/guides/idp/installation/#ormxmlworkaround"}}]},{"text":" for more details","type":"text"}]}]},{"type":"expand","attrs":{"title":"MemcachedStorageService"},"content":[{"type":"paragraph","content":[{"text":"Requirements","type":"text","marks":[{"type":"strong"}]},{"text":": memcached v1.4.14 or later","type":"text"}]},{"type":"paragraph","content":[{"text":"The memcached-based storage facility in IdPv3 is based on the ","type":"text"},{"text":"spymemcached library","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/couchbase/spymemcached"}}]},{"text":", which has a number of compelling features for HA deployments:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Optimized IO for high throughput","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Memcached failover facility","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Stable hashing algorithm supports memcached pool resizing","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The failover facility merits further discussion. Failover is enabled by specifying multiple memcached hosts and ","type":"text"},{"text":"failureMode=\"Redistribute\"","type":"text","marks":[{"type":"code"}]},{"text":". When the client encounters an unreachable host in redistribute mode, it will temporarily remove the unavailable host from the pool of available hosts. Any keys that hash to the unavailable host will be written or retrieved from a backup host. The high-level effect of this behavior on the IdP session management service is that a node failure will cause loss of IdP session, which would impact users as an unexpected authentication. The IdP session management service, however, would be fully functional during a host failure/recovery event. Also note that this behavior requires no state sharing (i.e. ","type":"text"},{"text":"repcache","type":"text","marks":[{"type":"em"}]},{"text":") between memcached nodes.","type":"text"}]},{"type":"paragraph","content":[{"text":"Bear in mind that different storage use cases have different failover properties. While the replay cache would be similarly unimpacted, the artifact map failing to retrieve a previously stored artifact mapping would result in a failed login to the service to which the artifact was sent.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following architecture is suggested for HA deployments that wish to use memcache:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":693,"id":"dac6d7d0-760c-45f0-9741-608a15ed168d","collection":"contentId-1265631707","type":"file","height":563}}]},{"type":"paragraph","content":[{"text":"Thus every IdP node runs a memcached service and the Java process running the IdP software connects to every memcached service. The following configuration example assumes the recommended architecture above and should be placed in ","type":"text"},{"text":"conf/global.xml .","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"MemcachedStorageService Configuration","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"46ad761c-abea-47b3-b5a4-653e7c1cbf55"}},{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n \n \n \n \n \n \n \n \n \n ","type":"text"}]},{"type":"paragraph","content":[{"text":"Once a MemcachedStorageService bean has been defined as above, it can be used with subsystems that require a StorageService component. The following configuration snippet from ","type":"text"},{"text":"conf/idp.properties","type":"text","marks":[{"type":"em"}]},{"text":" indicates how to use memcached for session storage.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Memcached for IdP Sessions","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"idp.session.StorageService = shibboleth.MemcachedStorageService","type":"text"}]},{"type":"paragraph"}]}],"version":1}