2 * Copyright 2001-2007 Internet2
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * @file shibsp/SessionCache.h
20 * Caches and manages user sessions
23 #ifndef __shibsp_sessioncache_h__
24 #define __shibsp_sessioncache_h__
26 #include <shibsp/base.h>
29 # include <saml/saml1/core/Assertions.h>
30 # include <saml/saml2/metadata/Metadata.h>
32 #include <xmltooling/Lockable.h>
36 class SHIBSP_API Application;
37 class SHIBSP_API Attribute;
39 class SHIBSP_API Session : public virtual xmltooling::Lockable
41 MAKE_NONCOPYABLE(Session);
47 * Returns the session key.
49 * @return unique ID of session
51 virtual const char* getID() const=0;
54 * Returns the address of the client associated with the session.
56 * @return the client's network address
58 virtual const char* getClientAddress() const=0;
61 * Returns the entityID of the IdP that initiated the session.
63 * @return the IdP's entityID
65 virtual const char* getEntityID() const=0;
68 * Returns the protocol family used to initiate the session.
70 * @return the protocol constant that represents the general SSO protocol used
72 virtual const char* getProtocol() const=0;
75 * Returns the UTC timestamp on the authentication event at the IdP.
77 * @return the UTC authentication timestamp
79 virtual const char* getAuthnInstant() const=0;
83 * Returns the NameID associated with a session.
85 * <p>SAML 1.x identifiers will be promoted to the 2.0 type.
87 * @return a SAML 2.0 NameID associated with the session, if any
89 virtual const opensaml::saml2::NameID* getNameID() const=0;
93 * Returns the SessionIndex provided with the session.
95 * @return the SessionIndex from the original SSO assertion, if any
97 virtual const char* getSessionIndex() const=0;
100 * Returns a URI containing an AuthnContextClassRef provided with the session.
102 * <p>SAML 1.x AuthenticationMethods will be returned as class references.
104 * @return a URI identifying the authentication context class
106 virtual const char* getAuthnContextClassRef() const=0;
109 * Returns a URI containing an AuthnContextDeclRef provided with the session.
111 * @return a URI identifying the authentication context declaration
113 virtual const char* getAuthnContextDeclRef() const=0;
116 * Returns the resolved attributes associated with the session.
118 * @return an immutable array of attributes
120 virtual const std::vector<Attribute*>& getAttributes() const=0;
123 * Returns the resolved attributes associated with the session, indexed by ID
125 * @return an immutable map of attributes keyed by attribute ID
127 virtual const std::multimap<std::string,const Attribute*>& getIndexedAttributes() const=0;
130 * Returns the identifiers of the assertion(s) cached by the session.
132 * <p>The SSO assertion is guaranteed to be first in the set.
134 * @return an immutable array of AssertionID values
136 virtual const std::vector<const char*>& getAssertionIDs() const=0;
140 * Adds additional attributes to the session.
142 * @param attributes reference to an array of Attributes to cache (will be freed by cache)
144 virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
147 * Returns an assertion cached by the session.
149 * @param id identifier of the assertion to retrieve
150 * @return pointer to assertion, or NULL
152 virtual const opensaml::Assertion* getAssertion(const char* id) const=0;
155 * Stores an assertion in the session.
157 * @param assertion pointer to an assertion to cache (will be freed by cache)
159 virtual void addAssertion(opensaml::Assertion* assertion)=0;
164 * Creates and manages user sessions
166 * The cache abstracts a persistent (meaning across requests) cache of
167 * instances of the Session interface. Creation of new entries and entry
168 * lookup are confined to this interface to enable the implementation to
169 * remote and/or optimize calls by implementing custom versions of the
170 * Session interface as required.
172 class SHIBSP_API SessionCache
174 MAKE_NONCOPYABLE(SessionCache);
180 * <p>The following XML content is supported to configure the cache:
182 * <dt>cacheTimeout</dt>
183 * <dd>attribute containing maximum lifetime in seconds for unused sessions to remain in cache</dd>
186 * @param e root of DOM tree to configure the cache
187 * @param defaultTimeout default cacheTimeout setting to use if none specified in DOM
189 SessionCache(const xercesc::DOMElement* e, unsigned long defaultTimeout=3600);
191 /** Maximum lifetime in seconds for unused sessions to be cached. */
192 unsigned long m_cacheTimeout;
195 virtual ~SessionCache() {}
199 * Inserts a new session into the cache.
201 * <p>The SSO tokens and Attributes remain owned by the caller and are copied by the cache.
203 * @param expires expiration time of session
204 * @param application reference to Application that owns the Session
205 * @param client_addr network address of client
206 * @param issuer issuing metadata of assertion issuer, if known
207 * @param protocol protocol family used to initiate the session
208 * @param nameid principal identifier, normalized to SAML 2, if any
209 * @param authn_instant UTC timestamp of authentication at IdP, if known
210 * @param session_index index of session between principal and IdP, if any
211 * @param authncontext_class method/category of authentication event, if known
212 * @param authncontext_decl specifics of authentication event, if known
213 * @param tokens assertions to cache with session, if any
214 * @param attributes optional array of resolved Attributes to cache with session
215 * @return newly created session's key
217 virtual std::string insert(
219 const Application& application,
220 const char* client_addr=NULL,
221 const opensaml::saml2md::EntityDescriptor* issuer=NULL,
222 const XMLCh* protocol=NULL,
223 const opensaml::saml2::NameID* nameid=NULL,
224 const XMLCh* authn_instant=NULL,
225 const XMLCh* session_index=NULL,
226 const XMLCh* authncontext_class=NULL,
227 const XMLCh* authncontext_decl=NULL,
228 const std::vector<const opensaml::Assertion*>* tokens=NULL,
229 const std::vector<Attribute*>* attributes=NULL
233 * Returns active sessions that match particular parameters and records the logout
234 * to prevent race conditions.
236 * <p>On exit, the mapping between these sessions and the associated information MAY be
237 * removed by the cache, so subsequent calls to this method may not return anything.
239 * <p>Until logout expiration, any attempt to create a session with the same parameters
240 * will be blocked by the cache.
242 * @param issuer source of session(s)
243 * @param nameid name identifier associated with the session(s) to terminate
244 * @param indexes indexes of sessions, or NULL for all sessions associated with other parameters
245 * @param expires logout expiration
246 * @param application reference to Application that owns the session(s)
247 * @param sessions on exit, contains the IDs of the matching sessions found
249 virtual std::vector<std::string>::size_type logout(
250 const opensaml::saml2md::EntityDescriptor* issuer,
251 const opensaml::saml2::NameID& nameid,
252 const std::set<std::string>* indexes,
254 const Application& application,
255 std::vector<std::string>& sessions
259 * Determines whether a given session (based on its ID) matches a set of input
262 * @param key session key to check
263 * @param issuer required source of session(s)
264 * @param nameid required name identifier
265 * @param indexes session indexes
266 * @param application reference to Application that owns the Session
267 * @return true iff the session matches the input criteria
269 virtual bool matches(
271 const opensaml::saml2md::EntityDescriptor* issuer,
272 const opensaml::saml2::NameID& nameid,
273 const std::set<std::string>* indexes,
274 const Application& application
278 * Executes a test of the cache's general health.
280 virtual void test()=0;
284 * Locates an existing session.
286 * <p>If the client address is supplied, then a check will be performed against
287 * the address recorded in the record.
289 * @param key session key
290 * @param application reference to Application that owns the Session
291 * @param client_addr network address of client (if known)
292 * @param timeout inactivity timeout to enforce (0 for none, NULL to bypass check/update of last access)
293 * @return pointer to locked Session, or NULL
295 virtual Session* find(
296 const char* key, const Application& application, const char* client_addr=NULL, time_t* timeout=NULL
300 * Deletes an existing session.
302 * @param key session key
303 * @param application reference to Application that owns the Session
305 virtual void remove(const char* key, const Application& application)=0;
309 /** SessionCache implementation backed by a StorageService. */
310 #define STORAGESERVICE_SESSION_CACHE "StorageService"
313 /** SessionCache implementation for lite builds that delegates to a remoted version. */
314 #define REMOTED_SESSION_CACHE "Remoted"
317 * Registers SessionCache classes into the runtime.
319 void SHIBSP_API registerSessionCaches();
322 #endif /* __shibsp_sessioncache_h__ */