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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file shibsp/handler/Handler.h
24 * Pluggable runtime functionality that implement protocols and services.
27 #ifndef __shibsp_handler_h__
28 #define __shibsp_handler_h__
30 #include <shibsp/SPRequest.h>
31 #include <shibsp/util/PropertySet.h>
36 class SAML_API SPSSODescriptor;
41 namespace xmltooling {
42 class XMLTOOL_API HTTPRequest;
43 class XMLTOOL_API HTTPResponse;
49 * Pluggable runtime functionality that implement protocols and services
51 class SHIBSP_API Handler : public virtual PropertySet
53 MAKE_NONCOPYABLE(Handler);
58 * Log using handler's specific logging object.
60 * @param level logging level
61 * @param msg message to log
63 virtual void log(SPRequest::SPLogLevel level, const std::string& msg) const;
66 * Prevents unused relay state from building up by cleaning old state from the client.
68 * <p>Handlers that generate relay state should call this method as a house cleaning
71 * @param application the associated Application
72 * @param request incoming HTTP request
73 * @param response outgoing HTTP response
75 virtual void cleanRelayState(
76 const Application& application, const xmltooling::HTTPRequest& request, xmltooling::HTTPResponse& response
80 * Implements various mechanisms to preserve RelayState,
81 * such as cookies or StorageService-backed keys.
83 * <p>If a supported mechanism can be identified, the input parameter will be
84 * replaced with a suitable state key.
86 * @param application the associated Application
87 * @param response outgoing HTTP response
88 * @param relayState RelayState token to supply with message
90 virtual void preserveRelayState(
91 const Application& application, xmltooling::HTTPResponse& response, std::string& relayState
95 * Implements various mechanisms to recover RelayState,
96 * such as cookies or StorageService-backed keys.
98 * <p>If a supported mechanism can be identified, the input parameter will be
99 * replaced with the recovered state information.
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
107 virtual void recoverRelayState(
108 const Application& application,
109 const xmltooling::HTTPRequest& request,
110 xmltooling::HTTPResponse& response,
111 std::string& relayState,
119 * Returns an identifier for the protocol family associated with the handler, if any.
121 * @return a protocol identifier, or nullptr
123 virtual const XMLCh* getProtocolFamily() const;
126 * Executes handler functionality as an incoming request.
128 * <p>Handlers can be run either directly by incoming web requests
129 * or indirectly/implicitly during other SP processing.
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
135 virtual std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const=0;
139 * Generates and/or modifies metadata reflecting the Handler.
141 * <p>The default implementation does nothing.
143 * @param role metadata role to decorate
144 * @param handlerURL base location of handler's endpoint
146 virtual void generateMetadata(opensaml::saml2md::SPSSODescriptor& role, const char* handlerURL) const;
149 * Returns the "type" of the Handler plugin.
151 * @return a Handler type
153 virtual const char* getType() const;
157 /** Registers Handler implementations. */
158 void SHIBSP_API registerHandlers();
160 /** Handler for SAML 1.x SSO. */
161 #define SAML1_ASSERTION_CONSUMER_SERVICE "SAML1"
163 /** Handler for SAML 2.0 SSO. */
164 #define SAML20_ASSERTION_CONSUMER_SERVICE "SAML2"
166 /** Handler for SAML 2.0 SLO. */
167 #define SAML20_LOGOUT_HANDLER "SAML2"
169 /** Handler for SAML 2.0 NIM. */
170 #define SAML20_NAMEID_MGMT_SERVICE "SAML2"
172 /** Handler for SAML 2.0 Artifact Resolution. */
173 #define SAML20_ARTIFACT_RESOLUTION_SERVICE "SAML2"
175 /** Handler for hooking new sessions with attribute checking. */
176 #define ATTR_CHECKER_HANDLER "AttributeChecker"
178 /** Handler for metadata generation. */
179 #define DISCOVERY_FEED_HANDLER "DiscoveryFeed"
181 /** Handler for external authentication integration. */
182 #define EXTERNAL_AUTH_HANDLER "ExternalAuth"
184 /** Handler for metadata generation. */
185 #define METADATA_GENERATOR_HANDLER "MetadataGenerator"
187 /** Handler for status information. */
188 #define STATUS_HANDLER "Status"
190 /** Handler for session diagnostic information. */
191 #define SESSION_HANDLER "Session"
194 #endif /* __shibsp_handler_h__ */