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