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