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 * Get the type of event, as input to error handling in response to errors raised by this handler. 158 * 159 * @return an event type for error handling 160 */ 161 virtual const char* getEventType() const; 162 }; 163 164 /** Registers Handler implementations. */ 165 void SHIBSP_API registerHandlers(); 166 167 /** Handler for SAML 1.x SSO. */ 168 #define SAML1_ASSERTION_CONSUMER_SERVICE "SAML1" 169 170 /** Handler for SAML 2.0 SSO. */ 171 #define SAML20_ASSERTION_CONSUMER_SERVICE "SAML2" 172 173 /** Handler for SAML 2.0 SLO. */ 174 #define SAML20_LOGOUT_HANDLER "SAML2" 175 176 /** Handler for SAML 2.0 NIM. */ 177 #define SAML20_NAMEID_MGMT_SERVICE "SAML2" 178 179 /** Handler for SAML 2.0 Artifact Resolution. */ 180 #define SAML20_ARTIFACT_RESOLUTION_SERVICE "SAML2" 181 182 /** Handler for hooking new sessions with attribute checking. */ 183 #define ATTR_CHECKER_HANDLER "AttributeChecker" 184 185 /** Handler for metadata generation. */ 186 #define DISCOVERY_FEED_HANDLER "DiscoveryFeed" 187 188 /** Handler for external authentication integration. */ 189 #define EXTERNAL_AUTH_HANDLER "ExternalAuth" 190 191 /** Handler for metadata generation. */ 192 #define METADATA_GENERATOR_HANDLER "MetadataGenerator" 193 194 /** Handler for status information. */ 195 #define STATUS_HANDLER "Status" 196 197 /** Handler for session diagnostic information. */ 198 #define SESSION_HANDLER "Session" 199 }; 200 201 #endif /* __shibsp_handler_h__ */ 202