shibsp/handler/Handler.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/Handler.h
  23  *
  24  * Pluggable runtime functionality that implement protocols and services.
  25  */
  26
  27 #ifndef __shibsp_handler_h__
  28 #define __shibsp_handler_h__
  29
  30 #include <shibsp/SPRequest.h>
  31 #include <shibsp/util/PropertySet.h>
  32
  33 #ifndef SHIBSP_LITE
  34 namespace opensaml {
  35     namespace saml2md {
  36         class SAML_API SPSSODescriptor;
  37     };
  38 };
  39 #endif
  40
  41 namespace xmltooling {
  42     class XMLTOOL_API HTTPRequest;
  43     class XMLTOOL_API HTTPResponse;
  44 };
  45
  46 namespace shibsp {
  47
  48     /**
  49      * Pluggable runtime functionality that implement protocols and services
  50      */
  51     class SHIBSP_API Handler : public virtual PropertySet
  52     {
  53         MAKE_NONCOPYABLE(Handler);
  54     protected:
  55         Handler();
  56
  57         /**
  58          * Log using handler's specific logging object.
  59          *
  60          * @param level logging level
  61          * @param msg   message to log
  62          */
  63         virtual void log(SPRequest::SPLogLevel level, const std::string& msg) const;
  64
  65         /**
  66          * Implements various mechanisms to preserve RelayState,
  67          * such as cookies or StorageService-backed keys.
  68          *
  69          * <p>If a supported mechanism can be identified, the input parameter will be
  70          * replaced with a suitable state key.
  71          *
  72          * @param application   the associated Application
  73          * @param response      outgoing HTTP response
  74          * @param relayState    RelayState token to supply with message
  75          */
  76         virtual void preserveRelayState(
  77             const Application& application, xmltooling::HTTPResponse& response, std::string& relayState
  78             ) const;
  79
  80         /**
  81          * Implements various mechanisms to recover RelayState,
  82          * such as cookies or StorageService-backed keys.
  83          *
  84          * <p>If a supported mechanism can be identified, the input parameter will be
  85          * replaced with the recovered state information.
  86          *
  87          * @param application   the associated Application
  88          * @param request       incoming HTTP request
  89          * @param response      outgoing HTTP response
  90          * @param relayState    RelayState token supplied with message
  91          * @param clear         true iff the token state should be cleared
  92          */
  93         virtual void recoverRelayState(
  94             const Application& application,
  95             const xmltooling::HTTPRequest& request,
  96             xmltooling::HTTPResponse& response,
  97             std::string& relayState,
  98             bool clear=true
  99             ) const;
 100
 101     public:
 102         virtual ~Handler();
 103
 104         /**
 105          * Returns an identifier for the protocol family associated with the handler, if any.
 106          *
 107          * @return  a protocol identifier, or nullptr
 108          */
 109         virtual const XMLCh* getProtocolFamily() const;
 110
 111         /**
 112          * Executes handler functionality as an incoming request.
 113          *
 114          * <p>Handlers can be run either directly by incoming web requests
 115          * or indirectly/implicitly during other SP processing.
 116          *
 117          * @param request   SP request context
 118          * @param isHandler true iff executing in the context of a direct handler invocation
 119          * @return  a pair containing a "request completed" indicator and a server-specific response code
 120          */
 121         virtual std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const=0;
 122
 123 #ifndef SHIBSP_LITE
 124         /**
 125          * Generates and/or modifies metadata reflecting the Handler.
 126          *
 127          * <p>The default implementation does nothing.
 128          *
 129          * @param role          metadata role to decorate
 130          * @param handlerURL    base location of handler's endpoint
 131          */
 132         virtual void generateMetadata(opensaml::saml2md::SPSSODescriptor& role, const char* handlerURL) const;
 133
 134         /**
 135          * Returns the "type" of the Handler plugin.
 136          *
 137          * @return  a Handler type
 138          */
 139         virtual const char* getType() const;
 140 #endif
 141     };
 142
 143     /** Registers Handler implementations. */
 144     void SHIBSP_API registerHandlers();
 145
 146     /** Handler for SAML 1.x SSO. */
 147     #define SAML1_ASSERTION_CONSUMER_SERVICE "SAML1"
 148
 149     /** Handler for SAML 2.0 SSO. */
 150     #define SAML20_ASSERTION_CONSUMER_SERVICE "SAML2"
 151
 152     /** Handler for SAML 2.0 SLO. */
 153     #define SAML20_LOGOUT_HANDLER "SAML2"
 154
 155     /** Handler for SAML 2.0 NIM. */
 156     #define SAML20_NAMEID_MGMT_SERVICE "SAML2"
 157
 158     /** Handler for SAML 2.0 Artifact Resolution. */
 159     #define SAML20_ARTIFACT_RESOLUTION_SERVICE "SAML2"
 160
 161     /** Handler for hooking new sessions with attribute checking. */
 162     #define ATTR_CHECKER_HANDLER "AttributeChecker"
 163
 164     /** Handler for metadata generation. */
 165     #define DISCOVERY_FEED_HANDLER "DiscoveryFeed"
 166
 167     /** Handler for metadata generation. */
 168     #define METADATA_GENERATOR_HANDLER "MetadataGenerator"
 169
 170     /** Handler for status information. */
 171     #define STATUS_HANDLER "Status"
 172
 173     /** Handler for session diagnostic information. */
 174     #define SESSION_HANDLER "Session"
 175 };
 176
 177 #endif /* __shibsp_handler_h__ */