shibsp/handler/LogoutHandler.h

   1 /*
   2  *  Copyright 2001-2009 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file shibsp/handler/LogoutHandler.h
  19  *
  20  * Base class for logout-related handlers.
  21  */
  22
  23 #ifndef __shibsp_logout_h__
  24 #define __shibsp_logout_h__
  25
  26 #include <shibsp/handler/RemotedHandler.h>
  27
  28 namespace shibsp {
  29
  30 #if defined (_MSC_VER)
  31     #pragma warning( push )
  32     #pragma warning( disable : 4251 )
  33 #endif
  34
  35     /**
  36      * Base class for logout-related handlers.
  37      */
  38     class SHIBSP_API LogoutHandler : public RemotedHandler
  39     {
  40     public:
  41         virtual ~LogoutHandler();
  42
  43         /**
  44          * The base method will iteratively attempt front-channel notification
  45          * of logout of the current session, and after the final round trip will
  46          * perform back-channel notification. Nothing will be done unless the
  47          * handler detects that it is the "top" level logout handler.
  48          * If the method returns false, then the specialized class should perform
  49          * its work assuming that the notifications are completed.
  50          *
  51          * Note that the current session is NOT removed from the cache.
  52          *
  53          * @param request   SP request context
  54          * @param isHandler true iff executing in the context of a direct handler invocation
  55          * @return  a pair containing a "request completed" indicator and a server-specific response code
  56          */
  57         std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
  58
  59         /**
  60          * A remoted procedure that will perform any necessary back-channel
  61          * notifications. The input structure must contain an "application_id" member,
  62          * and a "sessions" list containing the session keys, along with an integer
  63          * member called "notify" with a value of 1.
  64          *
  65          * @param in    incoming DDF message
  66          * @param out   stream to write outgoing DDF message to
  67          */
  68         void receive(DDF& in, std::ostream& out);
  69
  70     protected:
  71         LogoutHandler();
  72
  73         /** Flag indicating whether the subclass is acting as a LogoutInitiator. */
  74         bool m_initiator;
  75
  76         /** Array of query string parameters to preserve across front-channel notifications, if present. */
  77         std::vector<std::string> m_preserve;
  78
  79         /**
  80          * Perform front-channel logout notifications for an Application.
  81          *
  82          * @param application   the Application to notify
  83          * @param request       last request from browser
  84          * @param response      response to use for next notification
  85          * @param params        map of query string parameters to preserve across this notification
  86          * @return  indicator of a completed response along with the status code to return from the handler
  87          */
  88         std::pair<bool,long> notifyFrontChannel(
  89             const Application& application,
  90             const xmltooling::HTTPRequest& request,
  91             xmltooling::HTTPResponse& response,
  92             const std::map<std::string,std::string>* params=NULL
  93             ) const;
  94
  95         /**
  96          * Perform back-channel logout notifications for an Application.
  97          *
  98          * @param application   the Application to notify
  99          * @param requestURL    requestURL that resulted in method call
 100          * @param sessions      array of session keys being logged out
 101          * @param local         true iff the logout operation is local to the SP, false iff global
 102          * @return  true iff all notifications succeeded
 103          */
 104         bool notifyBackChannel(
 105             const Application& application, const char* requestURL, const std::vector<std::string>& sessions, bool local
 106             ) const;
 107
 108         /**
 109          * @deprecated
 110          * Sends a response template to the user agent informing it of the results of a logout attempt.
 111          *
 112          * @param application   the Application to use in determining the logout template
 113          * @param request       the HTTP client request to supply to the template
 114          * @param response      the HTTP response to use
 115          * @param local         true iff the logout operation was local to the SP, false iff global
 116          * @param status        optional logoutStatus key value to add to template
 117          */
 118         std::pair<bool,long> sendLogoutPage(
 119             const Application& application,
 120             const xmltooling::HTTPRequest& request,
 121             xmltooling::HTTPResponse& response,
 122             bool local=true,
 123             const char* status=NULL
 124             ) const;
 125
 126         /**
 127          * Sends a response template to the user agent informing it of the results of a logout attempt.
 128          *
 129          * @param application   the Application to use in determining the logout template
 130          * @param request       the HTTP client request to supply to the template
 131          * @param response      the HTTP response to use
 132          * @param type          designates the prefix of logout template name to use
 133          */
 134         std::pair<bool,long> sendLogoutPage(
 135             const Application& application,
 136             const xmltooling::HTTPRequest& request,
 137             xmltooling::HTTPResponse& response,
 138             const char* type
 139             ) const;
 140     };
 141
 142 #if defined (_MSC_VER)
 143     #pragma warning( pop )
 144 #endif
 145
 146     /** LogoutInitiator that iterates through a set of protocol-specific versions. */
 147     #define CHAINING_LOGOUT_INITIATOR "Chaining"
 148
 149     /** LogoutInitiator that supports SAML 2.0 LogoutRequests. */
 150     #define SAML2_LOGOUT_INITIATOR "SAML2"
 151
 152     /** LogoutInitiator that supports local-only logout. */
 153     #define LOCAL_LOGOUT_INITIATOR "Local"
 154
 155 };
 156
 157 #endif /* __shibsp_logout_h__ */