shibsp/SessionCache.h

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