shibsp/handler/AssertionConsumerService.h

   1 /*
   2  *  Copyright 2001-2009 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/AssertionConsumerService.h
  19  *
  20  * Base class for handlers that create sessions by consuming SSO protocol responses.
  21  */
  22
  23 #ifndef __shibsp_acshandler_h__
  24 #define __shibsp_acshandler_h__
  25
  26 #include <shibsp/handler/AbstractHandler.h>
  27 #include <shibsp/handler/RemotedHandler.h>
  28 #ifndef SHIBSP_LITE
  29 # include <saml/binding/MessageDecoder.h>
  30 # include <saml/saml1/core/Assertions.h>
  31 # include <saml/saml2/metadata/Metadata.h>
  32 #endif
  33 #include <xmltooling/unicode.h>
  34
  35 namespace shibsp {
  36
  37     class SHIBSP_API Attribute;
  38     class SHIBSP_API ResolutionContext;
  39
  40 #if defined (_MSC_VER)
  41     #pragma warning( push )
  42     #pragma warning( disable : 4250 )
  43 #endif
  44
  45     /**
  46      * Base class for handlers that create sessions by consuming SSO protocol responses.
  47      */
  48     class SHIBSP_API AssertionConsumerService : public AbstractHandler, public RemotedHandler
  49     {
  50     public:
  51         virtual ~AssertionConsumerService();
  52
  53         std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
  54         void receive(DDF& in, std::ostream& out);
  55
  56     protected:
  57         /**
  58          * Constructor
  59          *
  60          * @param e         root of DOM configuration
  61          * @param appId     ID of application that "owns" the handler
  62          * @param log       a logging object to use
  63          * @param filter    optional filter controls what child elements to include as nested PropertySets
  64          * @param remapper  optional map of property rename rules for legacy property support
  65          */
  66         AssertionConsumerService(
  67             const xercesc::DOMElement* e,
  68             const char* appId,
  69             xmltooling::logging::Category& log,
  70             xercesc::DOMNodeFilter* filter=NULL,
  71             const std::map<std::string,std::string>* remapper=NULL
  72             );
  73
  74         /**
  75          * Enforce address checking requirements.
  76          *
  77          * @param application   reference to application receiving message
  78          * @param httpRequest   client request that initiated session
  79          * @param issuedTo      address for which security assertion was issued
  80          */
  81         void checkAddress(const Application& application, const xmltooling::HTTPRequest& httpRequest, const char* issuedTo) const;
  82
  83 #ifndef SHIBSP_LITE
  84         void generateMetadata(opensaml::saml2md::SPSSODescriptor& role, const char* handlerURL) const;
  85
  86         /**
  87          * Returns a SecurityPolicy instance to use for an incoming request.
  88          *
  89          * <p>Allows handlers to customize the type of policy object their policy rules might require.
  90          * <p>The caller <strong>MUST</strong> lock the application's MetadataProvider for the life
  91          * of the returned object.
  92          *
  93          * @param application   reference to application receiving message
  94          * @param role          identifies the role (generally IdP or SP) of the policy peer
  95          * @param validate      true iff XML parsing should be done with validation
  96          * @param policyId      identifies policy rules to auto-attach, defaults to the application's set
  97          * @return  a new policy instance, which the caller is responsible for freeing
  98          */
  99         virtual opensaml::SecurityPolicy* createSecurityPolicy(
 100             const Application& application, const xmltooling::QName* role, bool validate, const char* policyId
 101             ) const;
 102
 103         /**
 104          * Implement protocol-specific handling of the incoming decoded message.
 105          *
 106          * <p>The result of implementing the protocol should be an exception or
 107          * modifications to the request/response objects to reflect processing
 108          * of the message.
 109          *
 110          * @param application   reference to application receiving message
 111          * @param httpRequest   client request that included message
 112          * @param httpResponse  response to client
 113          * @param policy        the SecurityPolicy in effect, after having evaluated the message
 114          * @param settings      policy configuration settings in effect
 115          * @param xmlObject     a protocol-specific message object
 116          */
 117         virtual void implementProtocol(
 118             const Application& application,
 119             const xmltooling::HTTPRequest& httpRequest,
 120             xmltooling::HTTPResponse& httpResponse,
 121             opensaml::SecurityPolicy& policy,
 122             const PropertySet* settings,
 123             const xmltooling::XMLObject& xmlObject
 124             ) const=0;
 125
 126         /**
 127          * Extracts policy-relevant assertion details.
 128          *
 129          * @param assertion the incoming assertion
 130          * @param protocol  the protocol family in use
 131          * @param policy    SecurityPolicy to provide various components and track message data
 132          */
 133         virtual void extractMessageDetails(
 134             const opensaml::Assertion& assertion, const XMLCh* protocol, opensaml::SecurityPolicy& policy
 135             ) const;
 136
 137         /**
 138          * Attempt SSO-initiated attribute resolution using the supplied information,
 139          * including NameID and token extraction and filtering followed by
 140          * secondary resolution.
 141          *
 142          * <p>The caller must free the returned context handle.
 143          *
 144          * @param application           reference to application receiving message
 145          * @param issuer                source of SSO tokens
 146          * @param protocol              SSO protocol used
 147          * @param v1nameid              identifier of principal in SAML 1.x form, if any
 148          * @param nameid                identifier of principal in SAML 2.0 form
 149          * @param authncontext_class    method/category of authentication event, if known
 150          * @param authncontext_decl     specifics of authentication event, if known
 151          * @param tokens                available assertions, if any
 152          */
 153         ResolutionContext* resolveAttributes(
 154             const Application& application,
 155             const opensaml::saml2md::RoleDescriptor* issuer=NULL,
 156             const XMLCh* protocol=NULL,
 157             const opensaml::saml1::NameIdentifier* v1nameid=NULL,
 158             const opensaml::saml2::NameID* nameid=NULL,
 159             const XMLCh* authncontext_class=NULL,
 160             const XMLCh* authncontext_decl=NULL,
 161             const std::vector<const opensaml::Assertion*>* tokens=NULL
 162             ) const;
 163
 164     public:
 165         const char* getType() const {
 166             return "AssertionConsumerService";
 167         }
 168
 169 #endif
 170     private:
 171         std::pair<bool,long> processMessage(
 172             const Application& application, const xmltooling::HTTPRequest& httpRequest, xmltooling::HTTPResponse& httpResponse
 173             ) const;
 174
 175         std::pair<bool,long> sendRedirect(
 176             const Application& application,
 177             const xmltooling::HTTPRequest& request,
 178             xmltooling::HTTPResponse& response,
 179             const char* entityID,
 180             const char* relayState
 181             ) const;
 182
 183         void maintainHistory(
 184             const Application& application, const xmltooling::HTTPRequest& request, xmltooling::HTTPResponse& response, const char* entityID
 185             ) const;
 186
 187 #ifndef SHIBSP_LITE
 188         opensaml::MessageDecoder* m_decoder;
 189         xmltooling::QName m_role;
 190 #endif
 191     };
 192
 193 #if defined (_MSC_VER)
 194     #pragma warning( pop )
 195 #endif
 196 };
 197
 198 #endif /* __shibsp_acshandler_h__ */