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