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>
27 #include <saml/saml1/core/Assertions.h>
28 #include <saml/saml2/metadata/Metadata.h>
29 #include <xmltooling/Lockable.h>
33 class SHIBSP_API Application;
34 class SHIBSP_API Attribute;
36 class SHIBSP_API Session : public virtual xmltooling::Lockable
38 MAKE_NONCOPYABLE(Session);
44 * Returns the address of the client associated with the session.
46 * @return the client's network address
48 virtual const char* getClientAddress() const=0;
51 * Returns the entityID of the IdP that initiated the session.
53 * @return the IdP's entityID
55 virtual const char* getEntityID() const=0;
58 * Returns the UTC timestamp on the authentication event at the IdP.
60 * @return the UTC authentication timestamp
62 virtual const char* getAuthnInstant() const=0;
65 * Returns the NameID associated with a session.
67 * <p>SAML 1.x identifiers will be promoted to the 2.0 type.
69 * @return reference to a SAML 2.0 NameID
71 virtual const opensaml::saml2::NameID& getNameID() const=0;
74 * Returns the SessionIndex provided with the session.
76 * @return the SessionIndex from the original SSO assertion, if any
78 virtual const char* getSessionIndex() const=0;
81 * Returns a URI containing an AuthnContextClassRef provided with the session.
83 * <p>SAML 1.x AuthenticationMethods will be returned as class references.
85 * @return a URI identifying the authentication context class
87 virtual const char* getAuthnContextClassRef() const=0;
90 * Returns a URI containing an AuthnContextDeclRef provided with the session.
92 * @return a URI identifying the authentication context declaration
94 virtual const char* getAuthnContextDeclRef() const=0;
97 * Returns the resolved attributes associated with the session.
99 * @return an immutable map of attributes keyed by attribute ID
101 virtual const std::map<std::string,const Attribute*>& getAttributes() const=0;
104 * Adds additional attributes to the session.
106 * @param attributes reference to an array of Attributes to cache (will be freed by cache)
108 virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
111 * Returns the identifiers of the assertion(s) cached by the session.
113 * <p>The SSO assertion is guaranteed to be first in the set.
115 * @return an immutable array of AssertionID values
117 virtual const std::vector<const char*>& getAssertionIDs() const=0;
120 * Returns an assertion cached by the session.
122 * @param id identifier of the assertion to retrieve
123 * @return pointer to assertion, or NULL
125 virtual const opensaml::RootObject* getAssertion(const char* id) const=0;
128 * Stores an assertion in the session.
130 * @param assertion pointer to an assertion to cache (will be freed by cache)
132 virtual void addAssertion(opensaml::RootObject* assertion)=0;
136 * Creates and manages user sessions
138 * The cache abstracts a persistent (meaning across requests) cache of
139 * instances of the Session interface. Creation of new entries and entry
140 * lookup are confined to this interface to enable the implementation to
141 * remote and/or optimize calls by implementing custom versions of the
142 * Session interface as required.
144 class SHIBSP_API SessionCache
146 MAKE_NONCOPYABLE(SessionCache);
152 * <p>The following XML content is supported to configure the cache:
154 * <dt>cacheTimeout</dt>
155 * <dd>attribute containing maximum lifetime in seconds for unused sessions to remain in cache</dd>
158 * @param e root of DOM tree to configure the cache
160 SessionCache(const DOMElement* e);
162 /** maximum lifetime in seconds for unused sessions to be cached */
163 unsigned long m_cacheTimeout;
166 virtual ~SessionCache() {}
169 * Inserts a new session into the cache.
171 * <p>The SSO token remains owned by the caller and is copied by the
172 * cache. Any Attributes supplied become the property of the cache.
174 * @param expires expiration time of session
175 * @param application reference to Application that owns the Session
176 * @param client_addr network address of client
177 * @param issuer issuing metadata of assertion issuer, if known
178 * @param nameid principal identifier, normalized to SAML 2
179 * @param authn_instant UTC timestamp of authentication at IdP
180 * @param session_index index of session between principal and IdP
181 * @param authncontext_class method/category of authentication event
182 * @param authncontext_decl specifics of authentication event
183 * @param tokens assertions to cache with session, if any
184 * @param attributes optional set of resolved Attributes to cache with session
185 * @return newly created session's key
187 virtual std::string insert(
189 const Application& application,
190 const char* client_addr,
191 const opensaml::saml2md::EntityDescriptor* issuer,
192 const opensaml::saml2::NameID& nameid,
193 const char* authn_instant=NULL,
194 const char* session_index=NULL,
195 const char* authncontext_class=NULL,
196 const char* authncontext_decl=NULL,
197 const std::vector<const opensaml::RootObject*>* tokens=NULL,
198 const std::vector<Attribute*>* attributes=NULL
202 * Locates an existing session.
204 * <p>If the client address is supplied, then a check will be performed against
205 * the address recorded in the record.
207 * @param key session key
208 * @param application reference to Application that owns the Session
209 * @param client_addr network address of client (if known)
210 * @param timeout inactivity timeout to enforce (0 for none)
211 * @return pointer to locked Session, or NULL
213 virtual Session* find(const char* key, const Application& application, const char* client_addr=NULL, time_t timeout=0)=0;
216 * Deletes an existing session.
218 * @param key session key
219 * @param application reference to Application that owns the Session
220 * @param client_addr network address of client (if known)
222 virtual void remove(const char* key, const Application& application, const char* client_addr)=0;
225 /** SessionCache implementation that delegates to a remoted version. */
226 #define REMOTED_SESSION_CACHE "Remoted"
228 /** SessionCache implementation backed by a StorageService. */
229 #define STORAGESERVICE_SESSION_CACHE "StorageService"
232 * Registers SessionCache classes into the runtime.
234 void SHIBSP_API registerSessionCaches();
237 #endif /* __shibsp_sessioncache_h__ */