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 address of the client associated with the session.
  48          *
  49          * @return  the client's network address
  50          */
  51         virtual const char* getClientAddress() const=0;
  52
  53         /**
  54          * Returns the entityID of the IdP that initiated the session.
  55          *
  56          * @return the IdP's entityID
  57          */
  58         virtual const char* getEntityID() const=0;
  59
  60         /**
  61          * Returns the UTC timestamp on the authentication event at the IdP.
  62          *
  63          * @return  the UTC authentication timestamp
  64          */
  65         virtual const char* getAuthnInstant() const=0;
  66
  67 #ifndef SHIBSP_LITE
  68         /**
  69          * Returns the NameID associated with a session.
  70          *
  71          * <p>SAML 1.x identifiers will be promoted to the 2.0 type.
  72          *
  73          * @return a SAML 2.0 NameID associated with the session, if any
  74          */
  75         virtual const opensaml::saml2::NameID* getNameID() const=0;
  76 #endif
  77
  78         /**
  79          * Returns the SessionIndex provided with the session.
  80          *
  81          * @return the SessionIndex from the original SSO assertion, if any
  82          */
  83         virtual const char* getSessionIndex() const=0;
  84
  85         /**
  86          * Returns a URI containing an AuthnContextClassRef provided with the session.
  87          *
  88          * <p>SAML 1.x AuthenticationMethods will be returned as class references.
  89          *
  90          * @return  a URI identifying the authentication context class
  91          */
  92         virtual const char* getAuthnContextClassRef() const=0;
  93
  94         /**
  95          * Returns a URI containing an AuthnContextDeclRef provided with the session.
  96          *
  97          * @return  a URI identifying the authentication context declaration
  98          */
  99         virtual const char* getAuthnContextDeclRef() const=0;
 100
 101         /**
 102          * Returns the resolved attributes associated with the session.
 103          *
 104          * @return an immutable map of attributes keyed by attribute ID
 105          */
 106         virtual const std::multimap<std::string,Attribute*>& getAttributes() const=0;
 107
 108         /**
 109          * Returns the identifiers of the assertion(s) cached by the session.
 110          *
 111          * <p>The SSO assertion is guaranteed to be first in the set.
 112          *
 113          * @return  an immutable array of AssertionID values
 114          */
 115         virtual const std::vector<const char*>& getAssertionIDs() const=0;
 116
 117 #ifndef SHIBSP_LITE
 118         /**
 119          * Adds additional attributes to the session.
 120          *
 121          * @param attributes    reference to an array of Attributes to cache (will be freed by cache)
 122          */
 123         virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
 124
 125         /**
 126          * Returns an assertion cached by the session.
 127          *
 128          * @param id    identifier of the assertion to retrieve
 129          * @return pointer to assertion, or NULL
 130          */
 131         virtual const opensaml::Assertion* getAssertion(const char* id) const=0;
 132
 133         /**
 134          * Stores an assertion in the session.
 135          *
 136          * @param assertion pointer to an assertion to cache (will be freed by cache)
 137          */
 138         virtual void addAssertion(opensaml::Assertion* assertion)=0;
 139 #endif
 140     };
 141
 142     /**
 143      * Creates and manages user sessions
 144      *
 145      * The cache abstracts a persistent (meaning across requests) cache of
 146      * instances of the Session interface. Creation of new entries and entry
 147      * lookup are confined to this interface to enable the implementation to
 148      * remote and/or optimize calls by implementing custom versions of the
 149      * Session interface as required.
 150      */
 151     class SHIBSP_API SessionCache
 152     {
 153         MAKE_NONCOPYABLE(SessionCache);
 154     protected:
 155
 156         /**
 157          * Constructor
 158          *
 159          * <p>The following XML content is supported to configure the cache:
 160          * <dl>
 161          *  <dt>cacheTimeout</dt>
 162          *  <dd>attribute containing maximum lifetime in seconds for unused sessions to remain in cache</dd>
 163          * </dl>
 164          *
 165          * @param e root of DOM tree to configure the cache
 166          */
 167         SessionCache(const xercesc::DOMElement* e);
 168
 169         /** maximum lifetime in seconds for unused sessions to be cached */
 170         unsigned long m_cacheTimeout;
 171
 172     public:
 173         virtual ~SessionCache() {}
 174
 175 #ifndef SHIBSP_LITE
 176         /**
 177          * Inserts a new session into the cache.
 178          *
 179          * <p>The SSO token remains owned by the caller and is copied by the
 180          * cache. Any Attributes supplied become the property of the cache.
 181          *
 182          * @param expires           expiration time of session
 183          * @param application       reference to Application that owns the Session
 184          * @param client_addr       network address of client
 185          * @param issuer            issuing metadata of assertion issuer, if known
 186          * @param nameid            principal identifier, normalized to SAML 2, if any
 187          * @param authn_instant     UTC timestamp of authentication at IdP, if known
 188          * @param session_index     index of session between principal and IdP, if any
 189          * @param authncontext_class    method/category of authentication event, if known
 190          * @param authncontext_decl specifics of authentication event, if known
 191          * @param tokens            assertions to cache with session, if any
 192          * @param attributes        optional map of resolved Attributes to cache with session
 193          * @return  newly created session's key
 194          */
 195         virtual std::string insert(
 196             time_t expires,
 197             const Application& application,
 198             const char* client_addr=NULL,
 199             const opensaml::saml2md::EntityDescriptor* issuer=NULL,
 200             const opensaml::saml2::NameID* nameid=NULL,
 201             const char* authn_instant=NULL,
 202             const char* session_index=NULL,
 203             const char* authncontext_class=NULL,
 204             const char* authncontext_decl=NULL,
 205             const std::vector<const opensaml::Assertion*>* tokens=NULL,
 206             const std::multimap<std::string,Attribute*>* attributes=NULL
 207             )=0;
 208 #endif
 209
 210         /**
 211          * Locates an existing session.
 212          *
 213          * <p>If the client address is supplied, then a check will be performed against
 214          * the address recorded in the record.
 215          *
 216          * @param key           session key
 217          * @param application   reference to Application that owns the Session
 218          * @param client_addr   network address of client (if known)
 219          * @param timeout       inactivity timeout to enforce (0 for none)
 220          * @return  pointer to locked Session, or NULL
 221          */
 222         virtual Session* find(const char* key, const Application& application, const char* client_addr=NULL, time_t timeout=0)=0;
 223
 224         /**
 225          * Deletes an existing session.
 226          *
 227          * @param key           session key
 228          * @param application   reference to Application that owns the Session
 229          * @param client_addr   network address of client (if known)
 230          */
 231         virtual void remove(const char* key, const Application& application, const char* client_addr)=0;
 232     };
 233
 234 #ifndef SHIBSP_LITE
 235     /** SessionCache implementation backed by a StorageService. */
 236     #define STORAGESERVICE_SESSION_CACHE    "StorageService"
 237 #endif
 238
 239     /** SessionCache implementation for lite builds that delegates to a remoted version. */
 240     #define REMOTED_SESSION_CACHE    "Remoted"
 241
 242     /**
 243      * Registers SessionCache classes into the runtime.
 244      */
 245     void SHIBSP_API registerSessionCaches();
 246 };
 247
 248 #endif /* __shibsp_sessioncache_h__ */