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