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