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