shibsp/ServiceProvider.h

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