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