2 * Licensed to the University Corporation for Advanced Internet
3 * Development, Inc. (UCAID) under one or more contributor license
4 * agreements. See the NOTICE file distributed with this work for
5 * additional information regarding copyright ownership.
7 * UCAID licenses this file to you under the Apache License,
8 * Version 2.0 (the "License"); you may not use this file except
9 * in compliance with the License. You may obtain a copy of the
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
17 * either express or implied. See the License for the specific
18 * language governing permissions and limitations under the License.
22 * @file shibsp/SessionCache.h
24 * Caches and manages user sessions.
27 #ifndef __shibsp_sessioncache_h__
28 #define __shibsp_sessioncache_h__
30 #include <shibsp/base.h>
37 #include <xercesc/util/XercesDefs.hpp>
38 #include <xmltooling/Lockable.h>
40 namespace xmltooling {
41 class XMLTOOL_API HTTPRequest;
42 class XMLTOOL_API HTTPResponse;
48 class SAML_API Assertion;
50 class SAML_API NameID;
53 class SAML_API EntityDescriptor;
60 class SHIBSP_API Application;
61 class SHIBSP_API Attribute;
64 * Encapsulates access to a user's security session.
66 * <p>The SessionCache does not itself require locking to manage
67 * concurrency, but access to each Session is generally exclusive
68 * or at least controlled, and the caller must unlock a Session
71 class SHIBSP_API Session : public virtual xmltooling::Lockable
73 MAKE_NONCOPYABLE(Session);
79 * Returns the session key.
81 * @return unique ID of session
83 virtual const char* getID() const=0;
86 * Returns the session's application ID.
88 * @return unique ID of application bound to session
90 virtual const char* getApplicationID() const=0;
93 * Returns the session expiration.
95 * @return the session's expiration time or 0 for none
97 virtual time_t getExpiration() const=0;
100 * Returns the last access time of the session.
102 * @return the session's last access time
104 virtual time_t getLastAccess() const=0;
107 * Returns the address of the client associated with the session.
109 * @return the client's network address
111 virtual const char* getClientAddress() const=0;
114 * Returns the entityID of the IdP that initiated the session.
116 * @return the IdP's entityID
118 virtual const char* getEntityID() const=0;
121 * Returns the protocol family used to initiate the session.
123 * @return the protocol constant that represents the general SSO protocol used
125 virtual const char* getProtocol() const=0;
128 * Returns the UTC timestamp on the authentication event at the IdP.
130 * @return the UTC authentication timestamp
132 virtual const char* getAuthnInstant() const=0;
136 * Returns the NameID associated with a session.
138 * <p>SAML 1.x identifiers will be promoted to the 2.0 type.
140 * @return a SAML 2.0 NameID associated with the session, if any
142 virtual const opensaml::saml2::NameID* getNameID() const=0;
146 * Returns the SessionIndex provided with the session.
148 * @return the SessionIndex from the original SSO assertion, if any
150 virtual const char* getSessionIndex() const=0;
153 * Returns a URI containing an AuthnContextClassRef provided with the session.
155 * <p>SAML 1.x AuthenticationMethods will be returned as class references.
157 * @return a URI identifying the authentication context class
159 virtual const char* getAuthnContextClassRef() const=0;
162 * Returns a URI containing an AuthnContextDeclRef provided with the session.
164 * @return a URI identifying the authentication context declaration
166 virtual const char* getAuthnContextDeclRef() const=0;
169 * Returns the resolved attributes associated with the session.
171 * @return an immutable array of attributes
173 virtual const std::vector<Attribute*>& getAttributes() const=0;
176 * Returns the resolved attributes associated with the session, indexed by ID
178 * @return an immutable map of attributes keyed by attribute ID
180 virtual const std::multimap<std::string,const Attribute*>& getIndexedAttributes() const=0;
183 * Returns the identifiers of the assertion(s) cached by the session.
185 * <p>The SSO assertion is guaranteed to be first in the set.
187 * @return an immutable array of AssertionID values
189 virtual const std::vector<const char*>& getAssertionIDs() const=0;
193 * Adds additional attributes to the session.
195 * @param attributes reference to an array of Attributes to cache (will be freed by cache)
197 virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
200 * Returns an assertion cached by the session.
202 * @param id identifier of the assertion to retrieve
203 * @return pointer to assertion, or nullptr
205 virtual const opensaml::Assertion* getAssertion(const char* id) const=0;
208 * Stores an assertion in the session.
210 * @param assertion pointer to an assertion to cache (will be freed by cache)
212 virtual void addAssertion(opensaml::Assertion* assertion)=0;
217 * Creates and manages user sessions
219 * The cache abstracts a persistent (meaning across requests) cache of
220 * instances of the Session interface. Creation of new entries and entry
221 * lookup are confined to this interface to enable the implementation to
222 * remote and/or optimize calls by implementing custom versions of the
223 * Session interface as required.
225 class SHIBSP_API SessionCache
227 MAKE_NONCOPYABLE(SessionCache);
231 virtual ~SessionCache();
236 * Inserts a new session into the cache and binds the session to the outgoing
239 * <p>The SSO tokens and Attributes remain owned by the caller and are copied by the cache.
241 * @param application reference to Application that owns the Session
242 * @param httpRequest request that initiated session
243 * @param httpResponse current response to client
244 * @param expires expiration time of session
245 * @param issuer issuing metadata of assertion issuer, if known
246 * @param protocol protocol family used to initiate the session
247 * @param nameid principal identifier, normalized to SAML 2, if any
248 * @param authn_instant UTC timestamp of authentication at IdP, if known
249 * @param session_index index of session between principal and IdP, if any
250 * @param authncontext_class method/category of authentication event, if known
251 * @param authncontext_decl specifics of authentication event, if known
252 * @param tokens assertions to cache with session, if any
253 * @param attributes optional array of resolved Attributes to cache with session
256 const Application& application,
257 const xmltooling::HTTPRequest& httpRequest,
258 xmltooling::HTTPResponse& httpResponse,
260 const opensaml::saml2md::EntityDescriptor* issuer=nullptr,
261 const XMLCh* protocol=nullptr,
262 const opensaml::saml2::NameID* nameid=nullptr,
263 const XMLCh* authn_instant=nullptr,
264 const XMLCh* session_index=nullptr,
265 const XMLCh* authncontext_class=nullptr,
266 const XMLCh* authncontext_decl=nullptr,
267 const std::vector<const opensaml::Assertion*>* tokens=nullptr,
268 const std::vector<Attribute*>* attributes=nullptr
272 * Inserts a new session into the cache and binds the session to the outgoing
275 * <p>The newly created session ID is placed into the first parameter.
277 * <p>The SSO tokens and Attributes remain owned by the caller and are copied by the cache.
279 * @param sessionID reference to string to capture newly inserted session ID
280 * @param application reference to Application that owns the Session
281 * @param httpRequest request that initiated session
282 * @param httpResponse current response to client
283 * @param expires expiration time of session
284 * @param issuer issuing metadata of assertion issuer, if known
285 * @param protocol protocol family used to initiate the session
286 * @param nameid principal identifier, normalized to SAML 2, if any
287 * @param authn_instant UTC timestamp of authentication at IdP, if known
288 * @param session_index index of session between principal and IdP, if any
289 * @param authncontext_class method/category of authentication event, if known
290 * @param authncontext_decl specifics of authentication event, if known
291 * @param tokens assertions to cache with session, if any
292 * @param attributes optional array of resolved Attributes to cache with session
295 std::string& sessionID,
296 const Application& application,
297 const xmltooling::HTTPRequest& httpRequest,
298 xmltooling::HTTPResponse& httpResponse,
300 const opensaml::saml2md::EntityDescriptor* issuer=nullptr,
301 const XMLCh* protocol=nullptr,
302 const opensaml::saml2::NameID* nameid=nullptr,
303 const XMLCh* authn_instant=nullptr,
304 const XMLCh* session_index=nullptr,
305 const XMLCh* authncontext_class=nullptr,
306 const XMLCh* authncontext_decl=nullptr,
307 const std::vector<const opensaml::Assertion*>* tokens=nullptr,
308 const std::vector<Attribute*>* attributes=nullptr
312 * Determines whether the Session bound to a client request matches a set of input criteria.
314 * @param application reference to Application that owns the Session
315 * @param request request in which to locate Session
316 * @param issuer required source of session(s)
317 * @param nameid required name identifier
318 * @param indexes session indexes
319 * @return true iff the Session exists and matches the input criteria
321 virtual bool matches(
322 const Application& application,
323 const xmltooling::HTTPRequest& request,
324 const opensaml::saml2md::EntityDescriptor* issuer,
325 const opensaml::saml2::NameID& nameid,
326 const std::set<std::string>* indexes
330 * Executes a test of the cache's general health.
332 virtual void test()=0;
336 * Returns the ID of the session bound to the specified client request, if possible.
338 * @param application reference to Application that owns the Session
339 * @param request request from client containing session, or a reference to it
340 * @return ID of session, if any known, or an empty string
342 virtual std::string active(const Application& application, const xmltooling::HTTPRequest& request)=0;
345 * Locates an existing session bound to a request.
347 * <p>If the client address is supplied, then a check will be performed against
348 * the address recorded in the record.
350 * @param application reference to Application that owns the Session
351 * @param request request from client bound to session
352 * @param client_addr network address of client (if known)
353 * @param timeout inactivity timeout to enforce (0 for none, nullptr to bypass check/update of last access)
354 * @return pointer to locked Session, or nullptr
356 virtual Session* find(
357 const Application& application,
358 const xmltooling::HTTPRequest& request,
359 const char* client_addr=nullptr,
360 time_t* timeout=nullptr
364 * Locates an existing session bound to a request.
366 * <p>If the client address is supplied, then a check will be performed against
367 * the address recorded in the record.
369 * <p>If a bound session is found to have expired, be invalid, etc., and if the request
370 * can be used to "clear" the session from subsequent client requests, then it may be cleared.
372 * @param application reference to Application that owns the Session
373 * @param request request from client bound to session
374 * @param client_addr network address of client (if known)
375 * @param timeout inactivity timeout to enforce (0 for none, nullptr to bypass check/update of last access)
376 * @return pointer to locked Session, or nullptr
378 virtual Session* find(
379 const Application& application,
380 xmltooling::HTTPRequest& request,
381 const char* client_addr=nullptr,
382 time_t* timeout=nullptr
386 * Deletes an existing session bound to a request.
388 * @param application reference to Application that owns the Session
389 * @param request request from client containing session, or a reference to it
390 * @param response optional response to client enabling removal of session or reference
392 virtual void remove(const Application& application, const xmltooling::HTTPRequest& request, xmltooling::HTTPResponse* response=nullptr)=0;
395 /** SessionCache implementation backed by a StorageService. */
396 #define STORAGESERVICE_SESSION_CACHE "StorageService"
399 * Registers SessionCache classes into the runtime.
401 void SHIBSP_API registerSessionCaches();
404 #endif /* __shibsp_sessioncache_h__ */