shibsp/SessionCache.h

   1 /*
   2  *  Copyright 2001-2006 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 #include <saml/saml1/core/Assertions.h>
  28 #include <saml/saml2/metadata/Metadata.h>
  29 #include <xmltooling/Lockable.h>
  30
  31 namespace shibsp {
  32
  33     class SHIBSP_API Application;
  34     class SHIBSP_API Attribute;
  35
  36     class SHIBSP_API Session : public virtual xmltooling::Lockable
  37     {
  38         MAKE_NONCOPYABLE(Session);
  39     protected:
  40         Session() {}
  41         virtual ~Session() {}
  42     public:
  43         /**
  44          * Returns the address of the client associated with the session.
  45          *
  46          * @return  the client's network address
  47          */
  48         virtual const char* getClientAddress() const=0;
  49
  50         /**
  51          * Returns the entityID of the IdP that initiated the session.
  52          *
  53          * @return the IdP's entityID
  54          */
  55         virtual const char* getEntityID() const=0;
  56
  57         /**
  58          * Returns the timestamp on the authentication event at the IdP.
  59          *
  60          * @return  the authentication timestamp
  61          */
  62         virtual time_t getAuthnInstant() const=0;
  63
  64         /**
  65          * Returns the set of resolved attributes associated with the session.
  66          *
  67          * @return an immutable array of attributes
  68          */
  69         virtual const std::vector<const Attribute*>& getAttributes() const=0;
  70
  71         /**
  72          * Adds additional attributes to the session.
  73          *
  74          * @param attributes    reference to an array of Attributes to cache (will be freed by cache)
  75          */
  76         virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
  77
  78         /**
  79          * Returns the identifiers of the assertion(s) cached by the session.
  80          *
  81          * <p>The SSO assertion is guaranteed to be first in the set.
  82          *
  83          * @return  an immutable array of AssertionID values
  84          */
  85         virtual const std::vector<const char*>& getAssertionIDs() const=0;
  86
  87         /**
  88          * Returns an assertion cached by the session.
  89          *
  90          * @param id    identifier of the assertion to retrieve
  91          * @return pointer to assertion, or NULL
  92          */
  93         virtual const opensaml::RootObject* getAssertion(const char* id) const=0;
  94
  95         /**
  96          * Stores an assertion in the session.
  97          *
  98          * @param assertion pointer to an assertion to cache (will be freed by cache)
  99          */
 100         virtual void addAssertion(opensaml::RootObject* assertion)=0;
 101     };
 102
 103     class SHIBSP_API SAML1Session : public virtual Session
 104     {
 105     protected:
 106         SAML1Session() {}
 107         virtual ~SAML1Session() {}
 108
 109     public:
 110         /**
 111          * Returns the NameIdentifier associated with a SAML 1.x session.
 112          *
 113          * @return reference to a SAML 1.x NameIdentifier
 114          */
 115         virtual const opensaml::saml1::NameIdentifier& getNameIdentifier() const=0;
 116
 117         /**
 118          * Returns a URI containing the AuthenticationMethod.
 119          *
 120          * @return  a URI identifying the authentication method
 121          */
 122         virtual const char* getAuthenticationMethod() const=0;
 123
 124     };
 125
 126     class SHIBSP_API SAML2Session : public virtual Session
 127     {
 128     protected:
 129         SAML2Session() {}
 130         virtual ~SAML2Session() {}
 131
 132     public:
 133         /**
 134          * Returns the NameID associated with a SAML 2.0 session.
 135          *
 136          * @return reference to a SAML 2.0 NameID
 137          */
 138         virtual const opensaml::saml2::NameID& getNameID() const=0;
 139
 140         /**
 141          * Returns the SessionIndex provided with the session.
 142          *
 143          * @return the SessionIndex from the original SSO assertion, if any
 144          */
 145         virtual const char* getSessionIndex() const=0;
 146
 147         /**
 148          * Returns a URI containing an AuthnContextClassRef provided with the session.
 149          *
 150          * @return  a URI identifying the authentication context class
 151          */
 152         virtual const char* getAuthnContextClassRef() const=0;
 153
 154         /**
 155          * Returns a URI containing an AuthnContextDeclRef provided with the session.
 156          *
 157          * @return  a URI identifying the authentication context declaration
 158          */
 159         virtual const char* getAuthnContextDeclRef() const=0;
 160
 161     };
 162
 163     /**
 164      * Creates and manages user sessions
 165      *
 166      * The cache abstracts a persistent (meaning across requests) cache of
 167      * instances of the Session interface. Creation of new entries and entry
 168      * lookup are confined to this interface to enable the implementation to
 169      * remote and/or optimize calls by implementing custom versions of the
 170      * Session interface as required.
 171      */
 172     class SHIBSP_API SessionCache
 173     {
 174         MAKE_NONCOPYABLE(SessionCache);
 175     protected:
 176
 177         /**
 178          * Constructor
 179          *
 180          * <p>The following XML content is supported to configure the cache:
 181          * <dl>
 182          *  <dt>cacheTimeout</dt>
 183          *  <dd>attribute containing maximum lifetime in seconds for sessions in cache</dd>
 184          *  <dt>cleanupInterval</dt>
 185          *  <dd>attribute containing interval in seconds between attempts to purge expired sessions</dd>
 186          *  <dt>strictValidity</dt>
 187          *  <dd>boolean attribute indicating whether to honor SessionNotOnOrAfter information</dd>
 188          *  <dt>writeThrough</dt>
 189          *  <dd>boolean attribute indicating that every access to a session should update persistent storage</dd>
 190          * </dl>
 191          *
 192          * @param e root of DOM tree to configure the cache
 193          */
 194         SessionCache(const DOMElement* e);
 195
 196     public:
 197         virtual ~SessionCache() {}
 198
 199         /**
 200          * Inserts a new session into the cache.
 201          *
 202          * <p>The SSO token remains owned by the caller and must be copied by the
 203          * cache. Any Attributes supplied become the property of the cache.
 204          *
 205          * @param application   reference to Application that owns the Session
 206          * @param client_addr   network address of client
 207          * @param ssoToken      reference to SSO assertion initiating the session
 208          * @param issuer        issuing metadata role of assertion issuer, if known
 209          * @param attributes    optional set of resolved Attributes to cache with session
 210          * @return  pointer to newly created (and locked) Session
 211          */
 212         virtual Session* insert(
 213             const Application& application,
 214             const char* client_addr,
 215             const opensaml::RootObject& ssoToken,
 216             const opensaml::saml2md::RoleDescriptor* issuer=NULL,
 217             const std::vector<Attribute*>* attributes=NULL
 218             )=0;
 219
 220         /**
 221          * Locates an existing session.
 222          *
 223          * @param key           session key
 224          * @param application   reference to Application that owns the Session
 225          * @param client_addr   network address of client (if known)
 226          * @return  pointer to locked Session, or NULL
 227          */
 228         virtual Session* find(const char* key, const Application& application, const char* client_addr)=0;
 229
 230         /**
 231          * Deletes an existing session.
 232          *
 233          * @param key           session key
 234          * @param application   reference to Application that owns the Session
 235          * @param client_addr   network address of client (if known)
 236          */
 237         virtual void remove(const char* key, const Application& application, const char* client_addr)=0;
 238     };
 239
 240     /** Remoting-aware SessionCache implementation backed by a StorageService. */
 241     #define STORAGESERVICE_SESSION_CACHE    "edu.internet2.middleware.shibboleth.sp.provider.StorageServiceSessionCache"
 242
 243     /**
 244      * Registers SessionCache classes into the runtime.
 245      */
 246     void SHIBSP_API registerSessionCaches();
 247 };
 248
 249 #endif /* __shibsp_sessioncache_h__ */