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