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