shibsp/SessionCache.h

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