shibsp/ServiceProvider.h

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