shibsp/handler/SessionInitiator.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/handler/SessionInitiator.h
  19  *
  20  * Pluggable runtime functionality that handles initiating sessions.
  21  */
  22
  23 #ifndef __shibsp_sesinitiator_h__
  24 #define __shibsp_sesinitiator_h__
  25
  26 #include <shibsp/handler/Handler.h>
  27
  28 #include <map>
  29 #include <set>
  30 #include <string>
  31
  32 namespace shibsp {
  33
  34     /**
  35      * Pluggable runtime functionality that handles initiating sessions.
  36      *
  37      * <p>By default, SessionInitiators look for an entityID on the incoming request
  38      * and pass control to the specialized run method.
  39      */
  40     class SHIBSP_API SessionInitiator : public virtual Handler
  41     {
  42         friend void SHIBSP_API registerSessionInitiators();
  43     protected:
  44         /** Property remapper for configuration compatibility. */
  45         static std::map<std::string,std::string> m_remapper;
  46
  47         /** Set of optional settings supported by handler. */
  48         std::set<std::string> m_supportedOptions;
  49
  50         SessionInitiator();
  51
  52         /**
  53          * Examines the request and applicable settings to determine whether
  54          * the handler is able to support the request.
  55          * <p>If the handler is within a chain, the method will return false,
  56          * otherwise an exception will be raised.
  57          *
  58          * @param request   SP request context
  59          * @param isHandler true iff executing in the context of a direct handler invocation
  60          * @return  true iff the request appears to be compatible
  61          */
  62         bool checkCompatibility(SPRequest& request, bool isHandler) const;
  63
  64     public:
  65         virtual ~SessionInitiator();
  66
  67         /**
  68          * Indicates the set of optional settings supported by the handler.
  69          *
  70          * @return  a set of the optional settings supported
  71          */
  72         virtual const std::set<std::string>& getSupportedOptions() const;
  73
  74         /**
  75          * Executes an incoming request.
  76          *
  77          * <p>SessionInitiators can be run either directly by incoming web requests
  78          * or indirectly/implicitly during other SP processing.
  79          *
  80          * @param request   SP request context
  81          * @param entityID  the name of an IdP to request a session from, if known
  82          * @param isHandler true iff executing in the context of a direct handler invocation
  83          * @return  a pair containing a "request completed" indicator and a server-specific response code
  84          */
  85         virtual std::pair<bool,long> run(SPRequest& request, std::string& entityID, bool isHandler=true) const=0;
  86
  87         std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
  88
  89 #ifndef SHIBSP_LITE
  90         const char* getType() const;
  91         void generateMetadata(opensaml::saml2md::SPSSODescriptor& role, const char* handlerURL) const;
  92 #endif
  93     };
  94
  95     /** Registers SessionInitiator implementations. */
  96     void SHIBSP_API registerSessionInitiators();
  97
  98     /** SessionInitiator that iterates through a set of protocol-specific versions. */
  99     #define CHAINING_SESSION_INITIATOR "Chaining"
 100
 101     /** SessionInitiator that supports SAML 2.0 AuthnRequests. */
 102     #define SAML2_SESSION_INITIATOR "SAML2"
 103
 104     /** SessionInitiator that supports SAML Discovery Service protocol. */
 105     #define SAMLDS_SESSION_INITIATOR "SAMLDS"
 106
 107     /** SessionInitiator that supports Shibboleth V1 AuthnRequest redirects. */
 108     #define SHIB1_SESSION_INITIATOR "Shib1"
 109
 110     /** SessionInitiator that supports Shibboleth V1 WAYF redirects when no IdP is supplied. */
 111     #define WAYF_SESSION_INITIATOR "WAYF"
 112
 113     /** SessionInitiator that attempts a sequence of transforms of an input until an entityID is found. */
 114     #define TRANSFORM_SESSION_INITIATOR "Transform"
 115
 116     /** SessionInitiator that uses HTML form submission from the user. */
 117     #define FORM_SESSION_INITIATOR "Form"
 118
 119     /** SessionInitiator that reads the CDC. */
 120     #define COOKIE_SESSION_INITIATOR "Cookie"
 121 };
 122
 123 #endif /* __shibsp_sesinitiator_h__ */