shibsp/handler/LogoutHandler.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/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     protected:
  79         LogoutHandler();
  80
  81         /** Flag indicating whether the subclass is acting as a LogoutInitiator. */
  82         bool m_initiator;
  83
  84         /** Array of query string parameters to preserve across front-channel notifications, if present. */
  85         std::vector<std::string> m_preserve;
  86
  87         /**
  88          * Perform front-channel logout notifications for an Application.
  89          *
  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
  95          */
  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
 101             ) const;
 102
 103         /**
 104          * Perform back-channel logout notifications for an Application.
 105          *
 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
 111          */
 112         bool notifyBackChannel(
 113             const Application& application, const char* requestURL, const std::vector<std::string>& sessions, bool local
 114             ) const;
 115
 116         /**
 117          * @deprecated
 118          * Sends a response template to the user agent informing it of the results of a logout attempt.
 119          *
 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
 125          */
 126         std::pair<bool,long> sendLogoutPage(
 127             const Application& application,
 128             const xmltooling::HTTPRequest& request,
 129             xmltooling::HTTPResponse& response,
 130             bool local=true,
 131             const char* status=nullptr
 132             ) const;
 133
 134         /**
 135          * Sends a response template to the user agent informing it of the results of a logout attempt.
 136          *
 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
 141          */
 142         std::pair<bool,long> sendLogoutPage(
 143             const Application& application,
 144             const xmltooling::HTTPRequest& request,
 145             xmltooling::HTTPResponse& response,
 146             const char* type
 147             ) const;
 148
 149 #ifndef SHIBSP_LITE
 150         /**
 151          * Creates a new LogoutEvent for the event log.
 152          *
 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
 157          */
 158         virtual LogoutEvent* newLogoutEvent(
 159             const Application& application,
 160             const xmltooling::HTTPRequest* request=nullptr,
 161             const Session* session=nullptr
 162             ) const;
 163 #endif
 164     };
 165
 166 #if defined (_MSC_VER)
 167     #pragma warning( pop )
 168 #endif
 169 };
 170
 171 #endif /* __shibsp_logout_h__ */