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/LogoutHandler.h 23 * 24 * Base class for logout-related handlers. 25 */ 26 27 #ifndef __shibsp_logout_h__ 28 #define __shibsp_logout_h__ 29 30 #include <shibsp/handler/RemotedHandler.h> 31 32 namespace shibsp { 33 34 #ifndef SHIBSP_LITE 35 class SHIBSP_API LogoutEvent; 36 #endif 37 38 #if defined (_MSC_VER) 39 #pragma warning( push ) 40 #pragma warning( disable : 4251 ) 41 #endif 42 43 /** 44 * Base class for logout-related handlers. 45 */ 46 class SHIBSP_API LogoutHandler : public RemotedHandler 47 { 48 public: 49 virtual ~LogoutHandler(); 50 51 /** 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. 58 * 59 * Note that the current session is NOT removed from the cache. 60 * 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 64 */ 65 std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const; 66 67 /** 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. 72 * 73 * @param in incoming DDF message 74 * @param out stream to write outgoing DDF message to 75 */ 76 void receive(DDF& in, std::ostream& out); 77 78 const char* getEventType() const; 79 80 protected: 81 LogoutHandler(); 82 83 /** Flag indicating whether the subclass is acting as a LogoutInitiator. */ 84 bool m_initiator; 85 86 /** Array of query string parameters to preserve across front-channel notifications, if present. */ 87 std::vector<std::string> m_preserve; 88 89 /** 90 * Perform front-channel logout notifications for an Application. 91 * 92 * @param application the Application to notify 93 * @param request last request from browser 94 * @param response response to use for next notification 95 * @param params map of query string parameters to preserve across this notification 96 * @return indicator of a completed response along with the status code to return from the handler 97 */ 98 std::pair<bool,long> notifyFrontChannel( 99 const Application& application, 100 const xmltooling::HTTPRequest& request, 101 xmltooling::HTTPResponse& response, 102 const std::map<std::string,std::string>* params=nullptr 103 ) const; 104 105 /** 106 * Perform back-channel logout notifications for an Application. 107 * 108 * @param application the Application to notify 109 * @param requestURL requestURL that resulted in method call 110 * @param sessions array of session keys being logged out 111 * @param local true iff the logout operation is local to the SP, false iff global 112 * @return true iff all notifications succeeded 113 */ 114 bool notifyBackChannel( 115 const Application& application, const char* requestURL, const std::vector<std::string>& sessions, bool local 116 ) const; 117 118 /** 119 * Sends a response template to the user agent informing it of the results of a logout attempt. 120 * 121 * @param application the Application to use in determining the logout template 122 * @param request the HTTP client request to supply to the template 123 * @param response the HTTP response to use 124 * @param type designates the prefix of logout template name to use 125 */ 126 std::pair<bool,long> sendLogoutPage( 127 const Application& application, 128 const xmltooling::HTTPRequest& request, 129 xmltooling::HTTPResponse& response, 130 const char* type 131 ) const; 132 133 #ifndef SHIBSP_LITE 134 /** 135 * Creates a new LogoutEvent for the event log. 136 * 137 * @param application the Application associated with the event 138 * @param request the HTTP client request associated with the event, or nullptr 139 * @param session the user session associated with the event, or nullptr 140 * @return a fresh LogoutEvent, prepopulated by the input parameters, or nullptr if an error occurs 141 */ 142 virtual LogoutEvent* newLogoutEvent( 143 const Application& application, 144 const xmltooling::HTTPRequest* request=nullptr, 145 const Session* session=nullptr 146 ) const; 147 #endif 148 }; 149 150 #if defined (_MSC_VER) 151 #pragma warning( pop ) 152 #endif 153 }; 154 155 #endif /* __shibsp_logout_h__ */ 156