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