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