shibsp/ServiceProvider.h

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