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 RequestMapper;
  47     class SHIBSP_API SessionCache;
  48     class SHIBSP_API SPRequest;
  49     class SHIBSP_API TemplateParameters;
  50 #ifndef SHIBSP_LITE
  51     class SHIBSP_API SecurityPolicyProvider;
  52     class SHIBSP_API TransactionLog;
  53 #endif
  54
  55     /**
  56      * Interface to a Shibboleth ServiceProvider instance.
  57      *
  58      * <p>A ServiceProvider exposes configuration and infrastructure services required
  59      * by the SP implementation, allowing a flexible configuration format.
  60      */
  61         class SHIBSP_API ServiceProvider : public virtual xmltooling::Lockable, public virtual PropertySet
  62     {
  63         MAKE_NONCOPYABLE(ServiceProvider);
  64     protected:
  65         ServiceProvider();
  66     public:
  67         virtual ~ServiceProvider();
  68
  69         /**
  70          * Loads a configuration and prepares the instance for use.
  71          *
  72          * <p>Implemented as a separate method so that services can rely on
  73          * other services while they initialize by accessing the ServiceProvider
  74          * from the SPConfig singleton.
  75          */
  76         virtual void init()=0;
  77
  78 #ifndef SHIBSP_LITE
  79         /**
  80          * Returns a TransactionLog instance.
  81          *
  82          * @return  a TransactionLog instance
  83          */
  84         virtual TransactionLog* getTransactionLog() const=0;
  85
  86         /**
  87          * Returns a StorageService instance based on an ID.
  88          *
  89          * @param id    a nullptr-terminated key identifying the StorageService to the configuration
  90          * @return  a StorageService if available, or nullptr
  91          */
  92         virtual xmltooling::StorageService* getStorageService(const char* id) const=0;
  93 #endif
  94
  95         /**
  96          * Returns a SessionCache instance.
  97          *
  98          * @param required  true iff an exception should be thrown if no SessionCache is available
  99          * @return  a SessionCache
 100          */
 101         virtual SessionCache* getSessionCache(bool required=true) const=0;
 102
 103         /**
 104          * Returns a ListenerService instance.
 105          *
 106          * @param required  true iff an exception should be thrown if no ListenerService is available
 107          * @return  a ListenerService
 108          */
 109         virtual ListenerService* getListenerService(bool required=true) const=0;
 110
 111 #ifndef SHIBSP_LITE
 112         /**
 113          * Returns a SecurityPolicyProvider instance.
 114          *
 115          * @param required true iff an exception should be thrown if no SecurityPolicyProvider is available
 116          * @return  a SecurityPolicyProvider
 117          */
 118         virtual SecurityPolicyProvider* getSecurityPolicyProvider(bool required=true) const;
 119
 120         /**
 121          * @deprecated
 122                  * Returns the security policy settings for an identified policy.
 123          *
 124                  * @param id    identifies the policy to return, or nullptr for default
 125          * @return a PropertySet
 126                  */
 127         virtual const PropertySet* getPolicySettings(const char* id) const=0;
 128
 129         /**
 130          * @deprecated
 131                  * Returns the security policy rules for an identified policy.
 132          *
 133                  * @param id    identifies the policy to return, or nullptr for default
 134          * @return an array of policy rules
 135                  */
 136         virtual const std::vector<const opensaml::SecurityPolicyRule*>& getPolicyRules(const char* id) const=0;
 137
 138         /**
 139          * Sets implementation-specific transport options.
 140          *
 141          * @param transport a SOAPTransport object
 142          * @return  true iff all options were successfully set
 143          */
 144         virtual bool setTransportOptions(xmltooling::SOAPTransport& transport) const=0;
 145 #endif
 146
 147         /**
 148          * Returns a RequestMapper instance.
 149          *
 150          * @param required  true iff an exception should be thrown if no RequestMapper is available
 151          * @return  a RequestMapper
 152          */
 153         virtual RequestMapper* getRequestMapper(bool required=true) const=0;
 154
 155         /**
 156          * Returns an Application instance matching the specified ID.
 157          *
 158          * @param applicationId the ID of the application, or nullptr for the default
 159          * @return  pointer to the application, or nullptr
 160          */
 161         virtual const Application* getApplication(const char* applicationId) const=0;
 162
 163         /**
 164          * Enforces requirements for an authenticated session.
 165          *
 166          * <p>If the return value's first member is true, then request processing should terminate
 167          * with the second member as a status value. If false, processing can continue.
 168          *
 169          * @param request   SP request interface
 170          * @param handler   true iff a request to a registered Handler location can be directly executed
 171          * @return a pair containing a "request completed" indicator and a server-specific response code
 172          */
 173         virtual std::pair<bool,long> doAuthentication(SPRequest& request, bool handler=false) const;
 174
 175         /**
 176          * Enforces authorization requirements based on the authenticated session.
 177          *
 178          * <p>If the return value's first member is true, then request processing should terminate
 179          * with the second member as a status value. If false, processing can continue.
 180          *
 181          * @param request   SP request interface
 182          * @return a pair containing a "request completed" indicator and a server-specific response code
 183          */
 184         virtual std::pair<bool,long> doAuthorization(SPRequest& request) const;
 185
 186         /**
 187          * Publishes session contents to the request in the form of headers or environment variables.
 188          *
 189          * <p>If the return value's first member is true, then request processing should terminate
 190          * with the second member as a status value. If false, processing can continue.
 191          *
 192          * @param request   SP request interface
 193          * @param requireSession    set to true iff an error should result if no session exists
 194          * @return a pair containing a "request completed" indicator and a server-specific response code
 195          */
 196         virtual std::pair<bool,long> doExport(SPRequest& request, bool requireSession=true) const;
 197
 198         /**
 199          * Services requests for registered Handler locations.
 200          *
 201          * <p>If the return value's first member is true, then request processing should terminate
 202          * with the second member as a status value. If false, processing can continue.
 203          *
 204          * @param request   SP request interface
 205          * @return a pair containing a "request completed" indicator and a server-specific response code
 206          */
 207         virtual std::pair<bool,long> doHandler(SPRequest& request) const;
 208     };
 209
 210     /**
 211      * Registers ServiceProvider classes into the runtime.
 212      */
 213     void SHIBSP_API registerServiceProviders();
 214
 215     /** SP based on integrated XML and native server configuration. */
 216     #define XML_SERVICE_PROVIDER "XML"
 217 };
 218
 219 #endif /* __shibsp_sp_h__ */