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 #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 UTC timestamp on the authentication event at the IdP.
  59          *
  60          * @return  the UTC authentication timestamp
  61          */
  62         virtual const char* getAuthnInstant() const=0;
  63
  64         /**
  65          * Returns the NameID associated with a session.
  66          *
  67          * <p>SAML 1.x identifiers will be promoted to the 2.0 type.
  68          *
  69          * @return reference to a SAML 2.0 NameID
  70          */
  71         virtual const opensaml::saml2::NameID& getNameID() const=0;
  72
  73         /**
  74          * Returns the SessionIndex provided with the session.
  75          *
  76          * @return the SessionIndex from the original SSO assertion, if any
  77          */
  78         virtual const char* getSessionIndex() const=0;
  79
  80         /**
  81          * Returns a URI containing an AuthnContextClassRef provided with the session.
  82          *
  83          * <p>SAML 1.x AuthenticationMethods will be returned as class references.
  84          *
  85          * @return  a URI identifying the authentication context class
  86          */
  87         virtual const char* getAuthnContextClassRef() const=0;
  88
  89         /**
  90          * Returns a URI containing an AuthnContextDeclRef provided with the session.
  91          *
  92          * @return  a URI identifying the authentication context declaration
  93          */
  94         virtual const char* getAuthnContextDeclRef() const=0;
  95
  96         /**
  97          * Returns the resolved attributes associated with the session.
  98          *
  99          * @return an immutable map of attributes keyed by attribute ID
 100          */
 101         virtual const std::map<std::string,const Attribute*>& getAttributes() const=0;
 102
 103         /**
 104          * Adds additional attributes to the session.
 105          *
 106          * @param attributes    reference to an array of Attributes to cache (will be freed by cache)
 107          */
 108         virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
 109
 110         /**
 111          * Returns the identifiers of the assertion(s) cached by the session.
 112          *
 113          * <p>The SSO assertion is guaranteed to be first in the set.
 114          *
 115          * @return  an immutable array of AssertionID values
 116          */
 117         virtual const std::vector<const char*>& getAssertionIDs() const=0;
 118
 119         /**
 120          * Returns an assertion cached by the session.
 121          *
 122          * @param id    identifier of the assertion to retrieve
 123          * @return pointer to assertion, or NULL
 124          */
 125         virtual const opensaml::RootObject* getAssertion(const char* id) const=0;
 126
 127         /**
 128          * Stores an assertion in the session.
 129          *
 130          * @param assertion pointer to an assertion to cache (will be freed by cache)
 131          */
 132         virtual void addAssertion(opensaml::RootObject* assertion)=0;
 133     };
 134
 135     /**
 136      * Creates and manages user sessions
 137      *
 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.
 143      */
 144     class SHIBSP_API SessionCache
 145     {
 146         MAKE_NONCOPYABLE(SessionCache);
 147     protected:
 148
 149         /**
 150          * Constructor
 151          *
 152          * <p>The following XML content is supported to configure the cache:
 153          * <dl>
 154          *  <dt>cacheTimeout</dt>
 155          *  <dd>attribute containing maximum lifetime in seconds for unused sessions to remain in cache</dd>
 156          * </dl>
 157          *
 158          * @param e root of DOM tree to configure the cache
 159          */
 160         SessionCache(const DOMElement* e);
 161
 162         /** maximum lifetime in seconds for unused sessions to be cached */
 163         unsigned long m_cacheTimeout;
 164
 165     public:
 166         virtual ~SessionCache() {}
 167
 168         /**
 169          * Inserts a new session into the cache.
 170          *
 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.
 173          *
 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 ssoToken          SSO assertion initiating the session, if any
 184          * @param attributes        optional set of resolved Attributes to cache with session
 185          * @return  newly created session's key
 186          */
 187         virtual std::string insert(
 188             time_t expires,
 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 opensaml::RootObject* ssoToken=NULL,
 198             const std::vector<Attribute*>* attributes=NULL
 199             )=0;
 200
 201         /**
 202          * Locates an existing session.
 203          *
 204          * <p>If the client address is supplied, then a check will be performed against
 205          * the address recorded in the record.
 206          *
 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
 212          */
 213         virtual Session* find(const char* key, const Application& application, const char* client_addr=NULL, time_t timeout=0)=0;
 214
 215         /**
 216          * Deletes an existing session.
 217          *
 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)
 221          */
 222         virtual void remove(const char* key, const Application& application, const char* client_addr)=0;
 223     };
 224
 225     /** SessionCache implementation that delegates to a remoted version. */
 226     #define REMOTED_SESSION_CACHE    "Remoted"
 227
 228     /** SessionCache implementation backed by a StorageService. */
 229     #define STORAGESERVICE_SESSION_CACHE    "StorageService"
 230
 231     /**
 232      * Registers SessionCache classes into the runtime.
 233      */
 234     void SHIBSP_API registerSessionCaches();
 235 };
 236
 237 #endif /* __shibsp_sessioncache_h__ */