shibsp/SessionCache.h

   1 /*
   2  *  Copyright 2001-2009 Internet2
   3  *
   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file shibsp/SessionCache.h
  19  *
  20  * Caches and manages user sessions.
  21  */
  22
  23 #ifndef __shibsp_sessioncache_h__
  24 #define __shibsp_sessioncache_h__
  25
  26 #include <shibsp/base.h>
  27
  28 #include <vector>
  29 #include <xmltooling/Lockable.h>
  30
  31 namespace xmltooling {
  32     class XMLTOOL_API HTTPRequest;
  33     class XMLTOOL_API HTTPResponse;
  34 };
  35
  36 #ifndef SHIBSP_LITE
  37 # include <set>
  38 namespace opensaml {
  39     class SAML_API Assertion;
  40     namespace saml2 {
  41         class SAML_API NameID;
  42     };
  43 };
  44 #endif
  45
  46 namespace shibsp {
  47
  48     class SHIBSP_API Application;
  49     class SHIBSP_API Attribute;
  50
  51     /**
  52      * Encapsulates access to a user's security session.
  53      *
  54      * <p>The SessionCache does not itself require locking to manage
  55      * concurrency, but access to each Session is generally exclusive
  56      * or at least controlled, and the caller must unlock a Session
  57      * to dispose of it.
  58      */
  59     class SHIBSP_API Session : public virtual xmltooling::Lockable
  60     {
  61         MAKE_NONCOPYABLE(Session);
  62     protected:
  63         Session();
  64         virtual ~Session();
  65     public:
  66         /**
  67          * Returns the session key.
  68          *
  69          * @return unique ID of session
  70          */
  71         virtual const char* getID() const=0;
  72
  73         /**
  74          * Returns the session's application ID.
  75          *
  76          * @return unique ID of application bound to session
  77          */
  78         virtual const char* getApplicationID() const=0;
  79
  80         /**
  81          * Returns the session expiration.
  82          *
  83          * @return  the session's expiration time or 0 for none
  84          */
  85         virtual time_t getExpiration() const=0;
  86
  87         /**
  88          * Returns the last access time of the session.
  89          *
  90          * @return  the session's last access time
  91          */
  92         virtual time_t getLastAccess() const=0;
  93
  94         /**
  95          * Returns the address of the client associated with the session.
  96          *
  97          * @return  the client's network address
  98          */
  99         virtual const char* getClientAddress() const=0;
 100
 101         /**
 102          * Returns the entityID of the IdP that initiated the session.
 103          *
 104          * @return the IdP's entityID
 105          */
 106         virtual const char* getEntityID() const=0;
 107
 108         /**
 109          * Returns the protocol family used to initiate the session.
 110          *
 111          * @return the protocol constant that represents the general SSO protocol used
 112          */
 113         virtual const char* getProtocol() const=0;
 114
 115         /**
 116          * Returns the UTC timestamp on the authentication event at the IdP.
 117          *
 118          * @return  the UTC authentication timestamp
 119          */
 120         virtual const char* getAuthnInstant() const=0;
 121
 122 #ifndef SHIBSP_LITE
 123         /**
 124          * Returns the NameID associated with a session.
 125          *
 126          * <p>SAML 1.x identifiers will be promoted to the 2.0 type.
 127          *
 128          * @return a SAML 2.0 NameID associated with the session, if any
 129          */
 130         virtual const opensaml::saml2::NameID* getNameID() const=0;
 131 #endif
 132
 133         /**
 134          * Returns the SessionIndex provided with the session.
 135          *
 136          * @return the SessionIndex from the original SSO assertion, if any
 137          */
 138         virtual const char* getSessionIndex() const=0;
 139
 140         /**
 141          * Returns a URI containing an AuthnContextClassRef provided with the session.
 142          *
 143          * <p>SAML 1.x AuthenticationMethods will be returned as class references.
 144          *
 145          * @return  a URI identifying the authentication context class
 146          */
 147         virtual const char* getAuthnContextClassRef() const=0;
 148
 149         /**
 150          * Returns a URI containing an AuthnContextDeclRef provided with the session.
 151          *
 152          * @return  a URI identifying the authentication context declaration
 153          */
 154         virtual const char* getAuthnContextDeclRef() const=0;
 155
 156         /**
 157          * Returns the resolved attributes associated with the session.
 158          *
 159          * @return an immutable array of attributes
 160          */
 161         virtual const std::vector<Attribute*>& getAttributes() const=0;
 162
 163         /**
 164          * Returns the resolved attributes associated with the session, indexed by ID
 165          *
 166          * @return an immutable map of attributes keyed by attribute ID
 167          */
 168         virtual const std::multimap<std::string,const Attribute*>& getIndexedAttributes() const=0;
 169
 170         /**
 171          * Returns the identifiers of the assertion(s) cached by the session.
 172          *
 173          * <p>The SSO assertion is guaranteed to be first in the set.
 174          *
 175          * @return  an immutable array of AssertionID values
 176          */
 177         virtual const std::vector<const char*>& getAssertionIDs() const=0;
 178
 179 #ifndef SHIBSP_LITE
 180         /**
 181          * Adds additional attributes to the session.
 182          *
 183          * @param attributes    reference to an array of Attributes to cache (will be freed by cache)
 184          */
 185         virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
 186
 187         /**
 188          * Returns an assertion cached by the session.
 189          *
 190          * @param id    identifier of the assertion to retrieve
 191          * @return pointer to assertion, or NULL
 192          */
 193         virtual const opensaml::Assertion* getAssertion(const char* id) const=0;
 194
 195         /**
 196          * Stores an assertion in the session.
 197          *
 198          * @param assertion pointer to an assertion to cache (will be freed by cache)
 199          */
 200         virtual void addAssertion(opensaml::Assertion* assertion)=0;
 201 #endif
 202     };
 203
 204     /**
 205      * Creates and manages user sessions
 206      *
 207      * The cache abstracts a persistent (meaning across requests) cache of
 208      * instances of the Session interface. Creation of new entries and entry
 209      * lookup are confined to this interface to enable the implementation to
 210      * remote and/or optimize calls by implementing custom versions of the
 211      * Session interface as required.
 212      */
 213     class SHIBSP_API SessionCache
 214     {
 215         MAKE_NONCOPYABLE(SessionCache);
 216     protected:
 217         SessionCache();
 218     public:
 219         virtual ~SessionCache();
 220
 221 #ifndef SHIBSP_LITE
 222         /**
 223          * Inserts a new session into the cache and binds the session to the outgoing
 224          * client response.
 225          *
 226          * <p>The SSO tokens and Attributes remain owned by the caller and are copied by the cache.
 227          *
 228          * @param application       reference to Application that owns the Session
 229          * @param httpRequest       request that initiated session
 230          * @param httpResponse      current response to client
 231          * @param expires           expiration time of session
 232          * @param issuer            issuing metadata of assertion issuer, if known
 233          * @param protocol          protocol family used to initiate the session
 234          * @param nameid            principal identifier, normalized to SAML 2, if any
 235          * @param authn_instant     UTC timestamp of authentication at IdP, if known
 236          * @param session_index     index of session between principal and IdP, if any
 237          * @param authncontext_class    method/category of authentication event, if known
 238          * @param authncontext_decl specifics of authentication event, if known
 239          * @param tokens            assertions to cache with session, if any
 240          * @param attributes        optional array of resolved Attributes to cache with session
 241          */
 242         virtual void insert(
 243             const Application& application,
 244             const xmltooling::HTTPRequest& httpRequest,
 245             xmltooling::HTTPResponse& httpResponse,
 246             time_t expires,
 247             const opensaml::saml2md::EntityDescriptor* issuer=NULL,
 248             const XMLCh* protocol=NULL,
 249             const opensaml::saml2::NameID* nameid=NULL,
 250             const XMLCh* authn_instant=NULL,
 251             const XMLCh* session_index=NULL,
 252             const XMLCh* authncontext_class=NULL,
 253             const XMLCh* authncontext_decl=NULL,
 254             const std::vector<const opensaml::Assertion*>* tokens=NULL,
 255             const std::vector<Attribute*>* attributes=NULL
 256             )=0;
 257
 258         /**
 259          * Determines whether the Session bound to a client request matches a set of input criteria.
 260          *
 261          * @param application   reference to Application that owns the Session
 262          * @param request       request in which to locate Session
 263          * @param issuer        required source of session(s)
 264          * @param nameid        required name identifier
 265          * @param indexes       session indexes
 266          * @return  true iff the Session exists and matches the input criteria
 267          */
 268         virtual bool matches(
 269             const Application& application,
 270             const xmltooling::HTTPRequest& request,
 271             const opensaml::saml2md::EntityDescriptor* issuer,
 272             const opensaml::saml2::NameID& nameid,
 273             const std::set<std::string>* indexes
 274             )=0;
 275
 276         /**
 277          * Executes a test of the cache's general health.
 278          */
 279         virtual void test()=0;
 280 #endif
 281
 282         /**
 283          * Returns the ID of the session bound to the specified client request, if possible.
 284          *
 285          * @param application   reference to Application that owns the Session
 286          * @param request       request from client containing session, or a reference to it
 287          * @return  ID of session, if any known, or an empty string
 288          */
 289         virtual std::string active(const Application& application, const xmltooling::HTTPRequest& request)=0;
 290
 291         /**
 292          * Locates an existing session bound to a request.
 293          *
 294          * <p>If the client address is supplied, then a check will be performed against
 295          * the address recorded in the record.
 296          *
 297          * @param application   reference to Application that owns the Session
 298          * @param request       request from client bound to session
 299          * @param client_addr   network address of client (if known)
 300          * @param timeout       inactivity timeout to enforce (0 for none, NULL to bypass check/update of last access)
 301          * @return  pointer to locked Session, or NULL
 302          */
 303         virtual Session* find(
 304             const Application& application,
 305             const xmltooling::HTTPRequest& request,
 306             const char* client_addr=NULL,
 307             time_t* timeout=NULL
 308             )=0;
 309
 310         /**
 311          * Locates an existing session bound to a request.
 312          *
 313          * <p>If the client address is supplied, then a check will be performed against
 314          * the address recorded in the record.
 315          *
 316          * <p>If a bound session is found to have expired, be invalid, etc., and if the request
 317          * can be used to "clear" the session from subsequent client requests, then it may be cleared.
 318          *
 319          * @param application   reference to Application that owns the Session
 320          * @param request       request from client bound to session
 321          * @param client_addr   network address of client (if known)
 322          * @param timeout       inactivity timeout to enforce (0 for none, NULL to bypass check/update of last access)
 323          * @return  pointer to locked Session, or NULL
 324          */
 325         virtual Session* find(
 326             const Application& application,
 327             xmltooling::HTTPRequest& request,
 328             const char* client_addr=NULL,
 329             time_t* timeout=NULL
 330             );
 331
 332         /**
 333          * Deletes an existing session bound to a request.
 334          *
 335          * @param application   reference to Application that owns the Session
 336          * @param request       request from client containing session, or a reference to it
 337          * @param response      optional response to client enabling removal of session or reference
 338          */
 339         virtual void remove(const Application& application, const xmltooling::HTTPRequest& request, xmltooling::HTTPResponse* response=NULL)=0;
 340     };
 341
 342     /** SessionCache implementation backed by a StorageService. */
 343     #define STORAGESERVICE_SESSION_CACHE    "StorageService"
 344
 345     /**
 346      * Registers SessionCache classes into the runtime.
 347      */
 348     void SHIBSP_API registerSessionCaches();
 349 };
 350
 351 #endif /* __shibsp_sessioncache_h__ */