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