shibsp/SessionCache.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file shibsp/SessionCache.h
  23  *
  24  * Caches and manages user sessions.
  25  */
  26
  27 #ifndef __shibsp_sessioncache_h__
  28 #define __shibsp_sessioncache_h__
  29
  30 #include <shibsp/base.h>
  31
  32 #include <map>
  33 #include <set>
  34 #include <string>
  35 #include <vector>
  36 #include <ctime>
  37 #include <xmltooling/Lockable.h>
  38
  39 namespace xmltooling {
  40     class XMLTOOL_API HTTPRequest;
  41     class XMLTOOL_API HTTPResponse;
  42 };
  43
  44 #ifndef SHIBSP_LITE
  45 # include <set>
  46 namespace opensaml {
  47     class SAML_API Assertion;
  48     namespace saml2 {
  49         class SAML_API NameID;
  50     };
  51     namespace saml2md {
  52         class SAML_API EntityDescriptor;
  53     };
  54 };
  55 #endif
  56
  57 namespace shibsp {
  58
  59     class SHIBSP_API Application;
  60     class SHIBSP_API Attribute;
  61
  62     /**
  63      * Encapsulates access to a user's security session.
  64      *
  65      * <p>The SessionCache does not itself require locking to manage
  66      * concurrency, but access to each Session is generally exclusive
  67      * or at least controlled, and the caller must unlock a Session
  68      * to dispose of it.
  69      */
  70     class SHIBSP_API Session : public virtual xmltooling::Lockable
  71     {
  72         MAKE_NONCOPYABLE(Session);
  73     protected:
  74         Session();
  75         virtual ~Session();
  76     public:
  77         /**
  78          * Returns the session key.
  79          *
  80          * @return unique ID of session
  81          */
  82         virtual const char* getID() const=0;
  83
  84         /**
  85          * Returns the session's application ID.
  86          *
  87          * @return unique ID of application bound to session
  88          */
  89         virtual const char* getApplicationID() const=0;
  90
  91         /**
  92          * Returns the session expiration.
  93          *
  94          * @return  the session's expiration time or 0 for none
  95          */
  96         virtual time_t getExpiration() const=0;
  97
  98         /**
  99          * Returns the last access time of the session.
 100          *
 101          * @return  the session's last access time
 102          */
 103         virtual time_t getLastAccess() const=0;
 104
 105         /**
 106          * Returns the address of the client associated with the session.
 107          *
 108          * @return  the client's network address
 109          */
 110         virtual const char* getClientAddress() const=0;
 111
 112         /**
 113          * Returns the entityID of the IdP that initiated the session.
 114          *
 115          * @return the IdP's entityID
 116          */
 117         virtual const char* getEntityID() const=0;
 118
 119         /**
 120          * Returns the protocol family used to initiate the session.
 121          *
 122          * @return the protocol constant that represents the general SSO protocol used
 123          */
 124         virtual const char* getProtocol() const=0;
 125
 126         /**
 127          * Returns the UTC timestamp on the authentication event at the IdP.
 128          *
 129          * @return  the UTC authentication timestamp
 130          */
 131         virtual const char* getAuthnInstant() const=0;
 132
 133 #ifndef SHIBSP_LITE
 134         /**
 135          * Returns the NameID associated with a session.
 136          *
 137          * <p>SAML 1.x identifiers will be promoted to the 2.0 type.
 138          *
 139          * @return a SAML 2.0 NameID associated with the session, if any
 140          */
 141         virtual const opensaml::saml2::NameID* getNameID() const=0;
 142 #endif
 143
 144         /**
 145          * Returns the SessionIndex provided with the session.
 146          *
 147          * @return the SessionIndex from the original SSO assertion, if any
 148          */
 149         virtual const char* getSessionIndex() const=0;
 150
 151         /**
 152          * Returns a URI containing an AuthnContextClassRef provided with the session.
 153          *
 154          * <p>SAML 1.x AuthenticationMethods will be returned as class references.
 155          *
 156          * @return  a URI identifying the authentication context class
 157          */
 158         virtual const char* getAuthnContextClassRef() const=0;
 159
 160         /**
 161          * Returns a URI containing an AuthnContextDeclRef provided with the session.
 162          *
 163          * @return  a URI identifying the authentication context declaration
 164          */
 165         virtual const char* getAuthnContextDeclRef() const=0;
 166
 167         /**
 168          * Returns the resolved attributes associated with the session.
 169          *
 170          * @return an immutable array of attributes
 171          */
 172         virtual const std::vector<Attribute*>& getAttributes() const=0;
 173
 174         /**
 175          * Returns the resolved attributes associated with the session, indexed by ID
 176          *
 177          * @return an immutable map of attributes keyed by attribute ID
 178          */
 179         virtual const std::multimap<std::string,const Attribute*>& getIndexedAttributes() const=0;
 180
 181         /**
 182          * Returns the identifiers of the assertion(s) cached by the session.
 183          *
 184          * <p>The SSO assertion is guaranteed to be first in the set.
 185          *
 186          * @return  an immutable array of AssertionID values
 187          */
 188         virtual const std::vector<const char*>& getAssertionIDs() const=0;
 189
 190 #ifndef SHIBSP_LITE
 191         /**
 192          * Adds additional attributes to the session.
 193          *
 194          * @param attributes    reference to an array of Attributes to cache (will be freed by cache)
 195          */
 196         virtual void addAttributes(const std::vector<Attribute*>& attributes)=0;
 197
 198         /**
 199          * Returns an assertion cached by the session.
 200          *
 201          * @param id    identifier of the assertion to retrieve
 202          * @return pointer to assertion, or nullptr
 203          */
 204         virtual const opensaml::Assertion* getAssertion(const char* id) const=0;
 205
 206         /**
 207          * Stores an assertion in the session.
 208          *
 209          * @param assertion pointer to an assertion to cache (will be freed by cache)
 210          */
 211         virtual void addAssertion(opensaml::Assertion* assertion)=0;
 212 #endif
 213     };
 214
 215     /**
 216      * Creates and manages user sessions
 217      *
 218      * The cache abstracts a persistent (meaning across requests) cache of
 219      * instances of the Session interface. Creation of new entries and entry
 220      * lookup are confined to this interface to enable the implementation to
 221      * remote and/or optimize calls by implementing custom versions of the
 222      * Session interface as required.
 223      */
 224     class SHIBSP_API SessionCache
 225     {
 226         MAKE_NONCOPYABLE(SessionCache);
 227     protected:
 228         SessionCache();
 229     public:
 230         virtual ~SessionCache();
 231
 232 #ifndef SHIBSP_LITE
 233         /**
 234          * @deprecated
 235          * Inserts a new session into the cache and binds the session to the outgoing
 236          * client response.
 237          *
 238          * <p>The SSO tokens and Attributes remain owned by the caller and are copied by the cache.
 239          *
 240          * @param application       reference to Application that owns the Session
 241          * @param httpRequest       request that initiated session
 242          * @param httpResponse      current response to client
 243          * @param expires           expiration time of session
 244          * @param issuer            issuing metadata of assertion issuer, if known
 245          * @param protocol          protocol family used to initiate the session
 246          * @param nameid            principal identifier, normalized to SAML 2, if any
 247          * @param authn_instant     UTC timestamp of authentication at IdP, if known
 248          * @param session_index     index of session between principal and IdP, if any
 249          * @param authncontext_class    method/category of authentication event, if known
 250          * @param authncontext_decl specifics of authentication event, if known
 251          * @param tokens            assertions to cache with session, if any
 252          * @param attributes        optional array of resolved Attributes to cache with session
 253          */
 254         virtual void insert(
 255             const Application& application,
 256             const xmltooling::HTTPRequest& httpRequest,
 257             xmltooling::HTTPResponse& httpResponse,
 258             time_t expires,
 259             const opensaml::saml2md::EntityDescriptor* issuer=nullptr,
 260             const XMLCh* protocol=nullptr,
 261             const opensaml::saml2::NameID* nameid=nullptr,
 262             const XMLCh* authn_instant=nullptr,
 263             const XMLCh* session_index=nullptr,
 264             const XMLCh* authncontext_class=nullptr,
 265             const XMLCh* authncontext_decl=nullptr,
 266             const std::vector<const opensaml::Assertion*>* tokens=nullptr,
 267             const std::vector<Attribute*>* attributes=nullptr
 268             )=0;
 269
 270         /**
 271          * Inserts a new session into the cache and binds the session to the outgoing
 272          * client response.
 273          *
 274          * <p>The newly created session ID is placed into the first parameter.
 275          *
 276          * <p>The SSO tokens and Attributes remain owned by the caller and are copied by the cache.
 277          *
 278          * @param sessionID         reference to string to capture newly inserted session ID
 279          * @param application       reference to Application that owns the Session
 280          * @param httpRequest       request that initiated session
 281          * @param httpResponse      current response to client
 282          * @param expires           expiration time of session
 283          * @param issuer            issuing metadata of assertion issuer, if known
 284          * @param protocol          protocol family used to initiate the session
 285          * @param nameid            principal identifier, normalized to SAML 2, if any
 286          * @param authn_instant     UTC timestamp of authentication at IdP, if known
 287          * @param session_index     index of session between principal and IdP, if any
 288          * @param authncontext_class    method/category of authentication event, if known
 289          * @param authncontext_decl specifics of authentication event, if known
 290          * @param tokens            assertions to cache with session, if any
 291          * @param attributes        optional array of resolved Attributes to cache with session
 292          */
 293         virtual void insert(
 294             std::string& sessionID,
 295             const Application& application,
 296             const xmltooling::HTTPRequest& httpRequest,
 297             xmltooling::HTTPResponse& httpResponse,
 298             time_t expires,
 299             const opensaml::saml2md::EntityDescriptor* issuer=nullptr,
 300             const XMLCh* protocol=nullptr,
 301             const opensaml::saml2::NameID* nameid=nullptr,
 302             const XMLCh* authn_instant=nullptr,
 303             const XMLCh* session_index=nullptr,
 304             const XMLCh* authncontext_class=nullptr,
 305             const XMLCh* authncontext_decl=nullptr,
 306             const std::vector<const opensaml::Assertion*>* tokens=nullptr,
 307             const std::vector<Attribute*>* attributes=nullptr
 308             );
 309
 310         /**
 311          * Determines whether the Session bound to a client request matches a set of input criteria.
 312          *
 313          * @param application   reference to Application that owns the Session
 314          * @param request       request in which to locate Session
 315          * @param issuer        required source of session(s)
 316          * @param nameid        required name identifier
 317          * @param indexes       session indexes
 318          * @return  true iff the Session exists and matches the input criteria
 319          */
 320         virtual bool matches(
 321             const Application& application,
 322             const xmltooling::HTTPRequest& request,
 323             const opensaml::saml2md::EntityDescriptor* issuer,
 324             const opensaml::saml2::NameID& nameid,
 325             const std::set<std::string>* indexes
 326             )=0;
 327
 328         /**
 329          * Executes a test of the cache's general health.
 330          */
 331         virtual void test()=0;
 332 #endif
 333
 334         /**
 335          * Returns the ID of the session bound to the specified client request, if possible.
 336          *
 337          * @param application   reference to Application that owns the Session
 338          * @param request       request from client containing session, or a reference to it
 339          * @return  ID of session, if any known, or an empty string
 340          */
 341         virtual std::string active(const Application& application, const xmltooling::HTTPRequest& request)=0;
 342
 343         /**
 344          * Locates an existing session bound to a request.
 345          *
 346          * <p>If the client address is supplied, then a check will be performed against
 347          * the address recorded in the record.
 348          *
 349          * @param application   reference to Application that owns the Session
 350          * @param request       request from client bound to session
 351          * @param client_addr   network address of client (if known)
 352          * @param timeout       inactivity timeout to enforce (0 for none, nullptr to bypass check/update of last access)
 353          * @return  pointer to locked Session, or nullptr
 354          */
 355         virtual Session* find(
 356             const Application& application,
 357             const xmltooling::HTTPRequest& request,
 358             const char* client_addr=nullptr,
 359             time_t* timeout=nullptr
 360             )=0;
 361
 362         /**
 363          * Locates an existing session bound to a request.
 364          *
 365          * <p>If the client address is supplied, then a check will be performed against
 366          * the address recorded in the record.
 367          *
 368          * <p>If a bound session is found to have expired, be invalid, etc., and if the request
 369          * can be used to "clear" the session from subsequent client requests, then it may be cleared.
 370          *
 371          * @param application   reference to Application that owns the Session
 372          * @param request       request from client bound to session
 373          * @param client_addr   network address of client (if known)
 374          * @param timeout       inactivity timeout to enforce (0 for none, nullptr to bypass check/update of last access)
 375          * @return  pointer to locked Session, or nullptr
 376          */
 377         virtual Session* find(
 378             const Application& application,
 379             xmltooling::HTTPRequest& request,
 380             const char* client_addr=nullptr,
 381             time_t* timeout=nullptr
 382             );
 383
 384         /**
 385          * Deletes an existing session bound to a request.
 386          *
 387          * @param application   reference to Application that owns the Session
 388          * @param request       request from client containing session, or a reference to it
 389          * @param response      optional response to client enabling removal of session or reference
 390          */
 391         virtual void remove(const Application& application, const xmltooling::HTTPRequest& request, xmltooling::HTTPResponse* response=nullptr)=0;
 392     };
 393
 394     /** SessionCache implementation backed by a StorageService. */
 395     #define STORAGESERVICE_SESSION_CACHE    "StorageService"
 396
 397     /**
 398      * Registers SessionCache classes into the runtime.
 399      */
 400     void SHIBSP_API registerSessionCaches();
 401 };
 402
 403 #endif /* __shibsp_sessioncache_h__ */