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 #if defined (_MSC_VER)
  35     #pragma warning( push )
  36     #pragma warning( disable : 4251 )
  37 #endif
  38
  39     /**
  40      * Base class for logout-related handlers.
  41      */
  42     class SHIBSP_API LogoutHandler : public RemotedHandler
  43     {
  44     public:
  45         virtual ~LogoutHandler();
  46
  47         /**
  48          * The base method will iteratively attempt front-channel notification
  49          * of logout of the current session, and after the final round trip will
  50          * perform back-channel notification. Nothing will be done unless the
  51          * handler detects that it is the "top" level logout handler.
  52          * If the method returns false, then the specialized class should perform
  53          * its work assuming that the notifications are completed.
  54          *
  55          * Note that the current session is NOT removed from the cache.
  56          *
  57          * @param request   SP request context
  58          * @param isHandler true iff executing in the context of a direct handler invocation
  59          * @return  a pair containing a "request completed" indicator and a server-specific response code
  60          */
  61         std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
  62
  63         /**
  64          * A remoted procedure that will perform any necessary back-channel
  65          * notifications. The input structure must contain an "application_id" member,
  66          * and a "sessions" list containing the session keys, along with an integer
  67          * member called "notify" with a value of 1.
  68          *
  69          * @param in    incoming DDF message
  70          * @param out   stream to write outgoing DDF message to
  71          */
  72         void receive(DDF& in, std::ostream& out);
  73
  74     protected:
  75         LogoutHandler();
  76
  77         /** Flag indicating whether the subclass is acting as a LogoutInitiator. */
  78         bool m_initiator;
  79
  80         /** Array of query string parameters to preserve across front-channel notifications, if present. */
  81         std::vector<std::string> m_preserve;
  82
  83         /**
  84          * Perform front-channel logout notifications for an Application.
  85          *
  86          * @param application   the Application to notify
  87          * @param request       last request from browser
  88          * @param response      response to use for next notification
  89          * @param params        map of query string parameters to preserve across this notification
  90          * @return  indicator of a completed response along with the status code to return from the handler
  91          */
  92         std::pair<bool,long> notifyFrontChannel(
  93             const Application& application,
  94             const xmltooling::HTTPRequest& request,
  95             xmltooling::HTTPResponse& response,
  96             const std::map<std::string,std::string>* params=nullptr
  97             ) const;
  98
  99         /**
 100          * Perform back-channel logout notifications for an Application.
 101          *
 102          * @param application   the Application to notify
 103          * @param requestURL    requestURL that resulted in method call
 104          * @param sessions      array of session keys being logged out
 105          * @param local         true iff the logout operation is local to the SP, false iff global
 106          * @return  true iff all notifications succeeded
 107          */
 108         bool notifyBackChannel(
 109             const Application& application, const char* requestURL, const std::vector<std::string>& sessions, bool local
 110             ) const;
 111
 112         /**
 113          * @deprecated
 114          * Sends a response template to the user agent informing it of the results of a logout attempt.
 115          *
 116          * @param application   the Application to use in determining the logout template
 117          * @param request       the HTTP client request to supply to the template
 118          * @param response      the HTTP response to use
 119          * @param local         true iff the logout operation was local to the SP, false iff global
 120          * @param status        optional logoutStatus key value to add to template
 121          */
 122         std::pair<bool,long> sendLogoutPage(
 123             const Application& application,
 124             const xmltooling::HTTPRequest& request,
 125             xmltooling::HTTPResponse& response,
 126             bool local=true,
 127             const char* status=nullptr
 128             ) const;
 129
 130         /**
 131          * Sends a response template to the user agent informing it of the results of a logout attempt.
 132          *
 133          * @param application   the Application to use in determining the logout template
 134          * @param request       the HTTP client request to supply to the template
 135          * @param response      the HTTP response to use
 136          * @param type          designates the prefix of logout template name to use
 137          */
 138         std::pair<bool,long> sendLogoutPage(
 139             const Application& application,
 140             const xmltooling::HTTPRequest& request,
 141             xmltooling::HTTPResponse& response,
 142             const char* type
 143             ) const;
 144     };
 145
 146 #if defined (_MSC_VER)
 147     #pragma warning( pop )
 148 #endif
 149 };
 150
 151 #endif /* __shibsp_logout_h__ */