shibsp/handler/Handler.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/Handler.h
  23  *
  24  * Pluggable runtime functionality that implement protocols and services.
  25  */
  26
  27 #ifndef __shibsp_handler_h__
  28 #define __shibsp_handler_h__
  29
  30 #include <shibsp/SPRequest.h>
  31 #include <shibsp/util/PropertySet.h>
  32
  33 #ifndef SHIBSP_LITE
  34 namespace opensaml {
  35     namespace saml2md {
  36         class SAML_API SPSSODescriptor;
  37     };
  38 };
  39 #endif
  40
  41 namespace xmltooling {
  42     class XMLTOOL_API HTTPRequest;
  43     class XMLTOOL_API HTTPResponse;
  44 };
  45
  46 namespace shibsp {
  47
  48     /**
  49      * Pluggable runtime functionality that implement protocols and services
  50      */
  51     class SHIBSP_API Handler : public virtual PropertySet
  52     {
  53         MAKE_NONCOPYABLE(Handler);
  54     protected:
  55         Handler();
  56
  57         /**
  58          * Log using handler's specific logging object.
  59          *
  60          * @param level logging level
  61          * @param msg   message to log
  62          */
  63         virtual void log(SPRequest::SPLogLevel level, const std::string& msg) const;
  64
  65         /**
  66          * Prevents unused relay state from building up by cleaning old state from the client.
  67          *
  68          * <p>Handlers that generate relay state should call this method as a house cleaning
  69          * step.
  70          *
  71          * @param application   the associated Application
  72          * @param request       incoming HTTP request
  73          * @param response      outgoing HTTP response
  74          */
  75         virtual void cleanRelayState(
  76             const Application& application, const xmltooling::HTTPRequest& request, xmltooling::HTTPResponse& response
  77             ) const;
  78
  79         /**
  80          * Implements various mechanisms to preserve RelayState,
  81          * such as cookies or StorageService-backed keys.
  82          *
  83          * <p>If a supported mechanism can be identified, the input parameter will be
  84          * replaced with a suitable state key.
  85          *
  86          * @param application   the associated Application
  87          * @param response      outgoing HTTP response
  88          * @param relayState    RelayState token to supply with message
  89          */
  90         virtual void preserveRelayState(
  91             const Application& application, xmltooling::HTTPResponse& response, std::string& relayState
  92             ) const;
  93
  94         /**
  95          * Implements various mechanisms to recover RelayState,
  96          * such as cookies or StorageService-backed keys.
  97          *
  98          * <p>If a supported mechanism can be identified, the input parameter will be
  99          * replaced with the recovered state information.
 100          *
 101          * @param application   the associated Application
 102          * @param request       incoming HTTP request
 103          * @param response      outgoing HTTP response
 104          * @param relayState    RelayState token supplied with message
 105          * @param clear         true iff the token state should be cleared
 106          */
 107         virtual void recoverRelayState(
 108             const Application& application,
 109             const xmltooling::HTTPRequest& request,
 110             xmltooling::HTTPResponse& response,
 111             std::string& relayState,
 112             bool clear=true
 113             ) const;
 114
 115     public:
 116         virtual ~Handler();
 117
 118         /**
 119          * Returns an identifier for the protocol family associated with the handler, if any.
 120          *
 121          * @return  a protocol identifier, or nullptr
 122          */
 123         virtual const XMLCh* getProtocolFamily() const;
 124
 125         /**
 126          * Executes handler functionality as an incoming request.
 127          *
 128          * <p>Handlers can be run either directly by incoming web requests
 129          * or indirectly/implicitly during other SP processing.
 130          *
 131          * @param request   SP request context
 132          * @param isHandler true iff executing in the context of a direct handler invocation
 133          * @return  a pair containing a "request completed" indicator and a server-specific response code
 134          */
 135         virtual std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const=0;
 136
 137 #ifndef SHIBSP_LITE
 138         /**
 139          * Generates and/or modifies metadata reflecting the Handler.
 140          *
 141          * <p>The default implementation does nothing.
 142          *
 143          * @param role          metadata role to decorate
 144          * @param handlerURL    base location of handler's endpoint
 145          */
 146         virtual void generateMetadata(opensaml::saml2md::SPSSODescriptor& role, const char* handlerURL) const;
 147
 148         /**
 149          * Returns the "type" of the Handler plugin.
 150          *
 151          * @return  a Handler type
 152          */
 153         virtual const char* getType() const;
 154 #endif
 155     };
 156
 157     /** Registers Handler implementations. */
 158     void SHIBSP_API registerHandlers();
 159
 160     /** Handler for SAML 1.x SSO. */
 161     #define SAML1_ASSERTION_CONSUMER_SERVICE "SAML1"
 162
 163     /** Handler for SAML 2.0 SSO. */
 164     #define SAML20_ASSERTION_CONSUMER_SERVICE "SAML2"
 165
 166     /** Handler for SAML 2.0 SLO. */
 167     #define SAML20_LOGOUT_HANDLER "SAML2"
 168
 169     /** Handler for SAML 2.0 NIM. */
 170     #define SAML20_NAMEID_MGMT_SERVICE "SAML2"
 171
 172     /** Handler for SAML 2.0 Artifact Resolution. */
 173     #define SAML20_ARTIFACT_RESOLUTION_SERVICE "SAML2"
 174
 175     /** Handler for hooking new sessions with attribute checking. */
 176     #define ATTR_CHECKER_HANDLER "AttributeChecker"
 177
 178     /** Handler for metadata generation. */
 179     #define DISCOVERY_FEED_HANDLER "DiscoveryFeed"
 180
 181     /** Handler for external authentication integration. */
 182     #define EXTERNAL_AUTH_HANDLER "ExternalAuth"
 183
 184     /** Handler for metadata generation. */
 185     #define METADATA_GENERATOR_HANDLER "MetadataGenerator"
 186
 187     /** Handler for status information. */
 188     #define STATUS_HANDLER "Status"
 189
 190     /** Handler for session diagnostic information. */
 191     #define SESSION_HANDLER "Session"
 192 };
 193
 194 #endif /* __shibsp_handler_h__ */