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