shibsp/ServiceProvider.h

   1 /*
   2  *  Copyright 2001-2010 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/ServiceProvider.h
  19  *
  20  * Interface to a Shibboleth ServiceProvider instance.
  21  */
  22
  23 #ifndef __shibsp_sp_h__
  24 #define __shibsp_sp_h__
  25
  26 #include <shibsp/util/PropertySet.h>
  27
  28 #include <xmltooling/Lockable.h>
  29
  30 namespace xmltooling {
  31     class XMLTOOL_API SOAPTransport;
  32     class XMLTOOL_API StorageService;
  33 };
  34
  35 #ifndef SHIBSP_LITE
  36 namespace opensaml {
  37     class SAML_API SecurityPolicyRule;
  38 };
  39 #endif
  40
  41 namespace shibsp {
  42
  43     class SHIBSP_API Application;
  44     class SHIBSP_API Handler;
  45     class SHIBSP_API ListenerService;
  46     class SHIBSP_API Remoted;
  47     class SHIBSP_API RequestMapper;
  48     class SHIBSP_API SessionCache;
  49     class SHIBSP_API SPRequest;
  50     class SHIBSP_API TemplateParameters;
  51 #ifndef SHIBSP_LITE
  52     class SHIBSP_API SecurityPolicyProvider;
  53     class SHIBSP_API TransactionLog;
  54 #endif
  55
  56 #if defined (_MSC_VER)
  57     #pragma warning( push )
  58     #pragma warning( disable : 4251 )
  59 #endif
  60
  61     /**
  62      * Interface to a Shibboleth ServiceProvider instance.
  63      *
  64      * <p>A ServiceProvider exposes configuration and infrastructure services required
  65      * by the SP implementation, allowing a flexible configuration format.
  66      */
  67         class SHIBSP_API ServiceProvider : public virtual xmltooling::Lockable, public virtual PropertySet
  68     {
  69         MAKE_NONCOPYABLE(ServiceProvider);
  70     protected:
  71         ServiceProvider();
  72     public:
  73         virtual ~ServiceProvider();
  74
  75         /**
  76          * Loads a configuration and prepares the instance for use.
  77          *
  78          * <p>Implemented as a separate method so that services can rely on
  79          * other services while they initialize by accessing the ServiceProvider
  80          * from the SPConfig singleton.
  81          */
  82         virtual void init()=0;
  83
  84 #ifndef SHIBSP_LITE
  85         /**
  86          * Returns a TransactionLog instance.
  87          *
  88          * @return  a TransactionLog instance
  89          */
  90         virtual TransactionLog* getTransactionLog() const=0;
  91
  92         /**
  93          * Returns a StorageService instance based on an ID.
  94          *
  95          * @param id    a nullptr-terminated key identifying the StorageService to the configuration
  96          * @return  a StorageService if available, or nullptr
  97          */
  98         virtual xmltooling::StorageService* getStorageService(const char* id) const=0;
  99 #endif
 100
 101         /**
 102          * Returns a SessionCache instance.
 103          *
 104          * @param required  true iff an exception should be thrown if no SessionCache is available
 105          * @return  a SessionCache
 106          */
 107         virtual SessionCache* getSessionCache(bool required=true) const=0;
 108
 109         /**
 110          * Returns a ListenerService instance.
 111          *
 112          * @param required  true iff an exception should be thrown if no ListenerService is available
 113          * @return  a ListenerService
 114          */
 115         virtual ListenerService* getListenerService(bool required=true) const=0;
 116
 117 #ifndef SHIBSP_LITE
 118         /**
 119          * Returns a SecurityPolicyProvider instance.
 120          *
 121          * @param required true iff an exception should be thrown if no SecurityPolicyProvider is available
 122          * @return  a SecurityPolicyProvider
 123          */
 124         virtual SecurityPolicyProvider* getSecurityPolicyProvider(bool required=true) const;
 125
 126         /**
 127          * @deprecated
 128                  * Returns the security policy settings for an identified policy.
 129          *
 130                  * @param id    identifies the policy to return, or nullptr for default
 131          * @return a PropertySet
 132                  */
 133         virtual const PropertySet* getPolicySettings(const char* id) const=0;
 134
 135         /**
 136          * @deprecated
 137                  * Returns the security policy rules for an identified policy.
 138          *
 139                  * @param id    identifies the policy to return, or nullptr for default
 140          * @return an array of policy rules
 141                  */
 142         virtual const std::vector<const opensaml::SecurityPolicyRule*>& getPolicyRules(const char* id) const=0;
 143
 144         /**
 145          * Sets implementation-specific transport options.
 146          *
 147          * @param transport a SOAPTransport object
 148          * @return  true iff all options were successfully set
 149          */
 150         virtual bool setTransportOptions(xmltooling::SOAPTransport& transport) const=0;
 151 #endif
 152
 153         /**
 154          * Returns a RequestMapper instance.
 155          *
 156          * @param required  true iff an exception should be thrown if no RequestMapper is available
 157          * @return  a RequestMapper
 158          */
 159         virtual RequestMapper* getRequestMapper(bool required=true) const=0;
 160
 161         /**
 162          * Returns an Application instance matching the specified ID.
 163          *
 164          * @param applicationId the ID of the application, or nullptr for the default
 165          * @return  pointer to the application, or nullptr
 166          */
 167         virtual const Application* getApplication(const char* applicationId) const=0;
 168
 169         /**
 170          * Enforces requirements for an authenticated session.
 171          *
 172          * <p>If the return value's first member is true, then request processing should terminate
 173          * with the second member as a status value. If false, processing can continue.
 174          *
 175          * @param request   SP request interface
 176          * @param handler   true iff a request to a registered Handler location can be directly executed
 177          * @return a pair containing a "request completed" indicator and a server-specific response code
 178          */
 179         virtual std::pair<bool,long> doAuthentication(SPRequest& request, bool handler=false) const;
 180
 181         /**
 182          * Enforces authorization requirements based on the authenticated session.
 183          *
 184          * <p>If the return value's first member is true, then request processing should terminate
 185          * with the second member as a status value. If false, processing can continue.
 186          *
 187          * @param request   SP request interface
 188          * @return a pair containing a "request completed" indicator and a server-specific response code
 189          */
 190         virtual std::pair<bool,long> doAuthorization(SPRequest& request) const;
 191
 192         /**
 193          * Publishes session contents to the request in the form of headers or environment variables.
 194          *
 195          * <p>If the return value's first member is true, then request processing should terminate
 196          * with the second member as a status value. If false, processing can continue.
 197          *
 198          * @param request   SP request interface
 199          * @param requireSession    set to true iff an error should result if no session exists
 200          * @return a pair containing a "request completed" indicator and a server-specific response code
 201          */
 202         virtual std::pair<bool,long> doExport(SPRequest& request, bool requireSession=true) const;
 203
 204         /**
 205          * Services requests for registered Handler locations.
 206          *
 207          * <p>If the return value's first member is true, then request processing should terminate
 208          * with the second member as a status value. If false, processing can continue.
 209          *
 210          * @param request   SP request interface
 211          * @return a pair containing a "request completed" indicator and a server-specific response code
 212          */
 213         virtual std::pair<bool,long> doHandler(SPRequest& request) const;
 214
 215         /**
 216          * Register for a message. Returns existing remote service, allowing message hooking.
 217          *
 218          * @param address   message address to register
 219          * @param svc       pointer to remote service
 220          * @return  previous service registered for message, if any
 221          */
 222         virtual Remoted* regListener(const char* address, Remoted* svc);
 223
 224         /**
 225          * Unregisters service from an address, possibly restoring an original.
 226          *
 227          * @param address   message address to modify
 228          * @param current   pointer to unregistering service
 229          * @param restore   service to "restore" registration for
 230          * @return  true iff the current service was still registered
 231          */
 232         virtual bool unregListener(const char* address, Remoted* current, Remoted* restore=nullptr);
 233
 234         /**
 235          * Returns current service registered at an address, if any.
 236          *
 237          * @param address message address to access
 238          * @return  registered service, or nullptr
 239          */
 240         virtual Remoted* lookupListener(const char* address) const;
 241
 242     private:
 243         std::map<std::string,Remoted*> m_listenerMap;
 244     };
 245
 246 #if defined (_MSC_VER)
 247     #pragma warning( pop )
 248 #endif
 249
 250     /**
 251      * Registers ServiceProvider classes into the runtime.
 252      */
 253     void SHIBSP_API registerServiceProviders();
 254
 255     /** SP based on integrated XML and native server configuration. */
 256     #define XML_SERVICE_PROVIDER "XML"
 257 };
 258
 259 #endif /* __shibsp_sp_h__ */