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/LogoutHandler.h
24 * Base class for logout-related handlers.
27 #ifndef __shibsp_logout_h__
28 #define __shibsp_logout_h__
30 #include <shibsp/handler/RemotedHandler.h>
35 class SHIBSP_API LogoutEvent;
38 #if defined (_MSC_VER)
39 #pragma warning( push )
40 #pragma warning( disable : 4251 )
44 * Base class for logout-related handlers.
46 class SHIBSP_API LogoutHandler : public RemotedHandler
49 virtual ~LogoutHandler();
52 * The base method will iteratively attempt front-channel notification
53 * of logout of the current session, and after the final round trip will
54 * perform back-channel notification. Nothing will be done unless the
55 * handler detects that it is the "top" level logout handler.
56 * If the method returns false, then the specialized class should perform
57 * its work assuming that the notifications are completed.
59 * Note that the current session is NOT removed from the cache.
61 * @param request SP request context
62 * @param isHandler true iff executing in the context of a direct handler invocation
63 * @return a pair containing a "request completed" indicator and a server-specific response code
65 std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
68 * A remoted procedure that will perform any necessary back-channel
69 * notifications. The input structure must contain an "application_id" member,
70 * and a "sessions" list containing the session keys, along with an integer
71 * member called "notify" with a value of 1.
73 * @param in incoming DDF message
74 * @param out stream to write outgoing DDF message to
76 void receive(DDF& in, std::ostream& out);
81 /** Flag indicating whether the subclass is acting as a LogoutInitiator. */
84 /** Array of query string parameters to preserve across front-channel notifications, if present. */
85 std::vector<std::string> m_preserve;
88 * Perform front-channel logout notifications for an Application.
90 * @param application the Application to notify
91 * @param request last request from browser
92 * @param response response to use for next notification
93 * @param params map of query string parameters to preserve across this notification
94 * @return indicator of a completed response along with the status code to return from the handler
96 std::pair<bool,long> notifyFrontChannel(
97 const Application& application,
98 const xmltooling::HTTPRequest& request,
99 xmltooling::HTTPResponse& response,
100 const std::map<std::string,std::string>* params=nullptr
104 * Perform back-channel logout notifications for an Application.
106 * @param application the Application to notify
107 * @param requestURL requestURL that resulted in method call
108 * @param sessions array of session keys being logged out
109 * @param local true iff the logout operation is local to the SP, false iff global
110 * @return true iff all notifications succeeded
112 bool notifyBackChannel(
113 const Application& application, const char* requestURL, const std::vector<std::string>& sessions, bool local
118 * Sends a response template to the user agent informing it of the results of a logout attempt.
120 * @param application the Application to use in determining the logout template
121 * @param request the HTTP client request to supply to the template
122 * @param response the HTTP response to use
123 * @param local true iff the logout operation was local to the SP, false iff global
124 * @param status optional logoutStatus key value to add to template
126 std::pair<bool,long> sendLogoutPage(
127 const Application& application,
128 const xmltooling::HTTPRequest& request,
129 xmltooling::HTTPResponse& response,
131 const char* status=nullptr
135 * Sends a response template to the user agent informing it of the results of a logout attempt.
137 * @param application the Application to use in determining the logout template
138 * @param request the HTTP client request to supply to the template
139 * @param response the HTTP response to use
140 * @param type designates the prefix of logout template name to use
142 std::pair<bool,long> sendLogoutPage(
143 const Application& application,
144 const xmltooling::HTTPRequest& request,
145 xmltooling::HTTPResponse& response,
151 * Creates a new LogoutEvent for the event log.
153 * @param application the Application associated with the event
154 * @param request the HTTP client request associated with the event, or nullptr
155 * @param session the user session associated with the event, or nullptr
156 * @return a fresh LogoutEvent, prepopulated by the input parameters, or nullptr if an error occurs
158 virtual LogoutEvent* newLogoutEvent(
159 const Application& application,
160 const xmltooling::HTTPRequest* request=nullptr,
161 const Session* session=nullptr
166 #if defined (_MSC_VER)
167 #pragma warning( pop )
171 #endif /* __shibsp_logout_h__ */