shibsp/handler/LogoutHandler.h

   1 /*
   2  *  Copyright 2001-2007 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/SPRequest.h>
  27 #include <shibsp/handler/RemotedHandler.h>
  28
  29 namespace shibsp {
  30
  31 #if defined (_MSC_VER)
  32     #pragma warning( push )
  33     #pragma warning( disable : 4251 )
  34 #endif
  35
  36     /**
  37      * Base class for logout-related handlers.
  38      */
  39     class SHIBSP_API LogoutHandler : public RemotedHandler
  40     {
  41     public:
  42         virtual ~LogoutHandler() {}
  43
  44         /**
  45          * The base method will iteratively attempt front-channel notification
  46          * of logout of the current session, and after the final round trip will
  47          * perform back-channel notification. Nothing will be done unless the
  48          * handler detects that it is the "top" level logout handler.
  49          * If the method returns false, then the specialized class should perform
  50          * its work assuming that the notifications are completed.
  51          *
  52          * Note that the current session is NOT removed from the cache.
  53          *
  54          * @param request   SP request context
  55          * @param isHandler true iff executing in the context of a direct handler invocation
  56          * @return  a pair containing a "request completed" indicator and a server-specific response code
  57          */
  58         std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
  59
  60         /**
  61          * A remoted procedure that will perform any necessary back-channel
  62          * notifications. The input structure must contain an "application_id" member,
  63          * and a "sessions" list containing the session keys, along with an integer
  64          * member called "notify" with a value of 1.
  65          *
  66          * @param in    incoming DDF message
  67          * @param out   stream to write outgoing DDF message to
  68          */
  69         void receive(DDF& in, std::ostream& out);
  70
  71     protected:
  72         LogoutHandler() : m_initiator(true) {}
  73
  74         /** Flag indicating whether the subclass is acting as a LogoutInitiator. */
  75         bool m_initiator;
  76
  77         /** Array of query string parameters to preserve across front-channel notifications, if present. */
  78         std::vector<std::string> m_preserve;
  79
  80         /**
  81          * Perform front-channel logout notifications for an Application.
  82          *
  83          * @param application   the Application to notify
  84          * @param request       last request from browser
  85          * @param response      response to use for next notification
  86          * @param params        map of query string parameters to preserve across this notification
  87          * @return  indicator of a completed response along with the status code to return from the handler
  88          */
  89         std::pair<bool,long> notifyFrontChannel(
  90             const Application& application,
  91             const xmltooling::HTTPRequest& request,
  92             xmltooling::HTTPResponse& response,
  93             const std::map<std::string,std::string>* params=NULL
  94             ) const;
  95
  96         /**
  97          * Perform back-channel logout notifications for an Application.
  98          *
  99          * @param application   the Application to notify
 100          * @param requestURL    requestURL that resulted in method call
 101          * @param sessions      array of session keys being logged out
 102          * @param local         true iff the logout operation is local to the SP, false iff global
 103          * @return  true iff all notifications succeeded
 104          */
 105         bool notifyBackChannel(
 106             const Application& application, const char* requestURL, const std::vector<std::string>& sessions, bool local
 107             ) const;
 108
 109         /**
 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 #if defined (_MSC_VER)
 128     #pragma warning( pop )
 129 #endif
 130
 131     /** LogoutInitiator that iterates through a set of protocol-specific versions. */
 132     #define CHAINING_LOGOUT_INITIATOR "Chaining"
 133
 134     /** LogoutInitiator that supports SAML 2.0 LogoutRequests. */
 135     #define SAML2_LOGOUT_INITIATOR "SAML2"
 136
 137     /** LogoutInitiator that supports local-only logout. */
 138     #define LOCAL_LOGOUT_INITIATOR "Local"
 139
 140 };
 141
 142 #endif /* __shibsp_logout_h__ */