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