2 * Copyright 2001-2011 Internet2
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file shibsp/ServiceProvider.h
20 * Interface to a Shibboleth ServiceProvider instance.
23 #ifndef __shibsp_sp_h__
24 #define __shibsp_sp_h__
26 #include <shibsp/util/PropertySet.h>
30 #include <xmltooling/Lockable.h>
32 namespace xmltooling {
33 class XMLTOOL_API SOAPTransport;
34 class XMLTOOL_API StorageService;
39 class SAML_API SecurityPolicyRule;
45 class SHIBSP_API Application;
46 class SHIBSP_API Handler;
47 class SHIBSP_API ListenerService;
48 class SHIBSP_API Remoted;
49 class SHIBSP_API RequestMapper;
50 class SHIBSP_API SessionCache;
51 class SHIBSP_API SPRequest;
52 class SHIBSP_API TemplateParameters;
54 class SHIBSP_API SecurityPolicyProvider;
55 class SHIBSP_API TransactionLog;
58 #if defined (_MSC_VER)
59 #pragma warning( push )
60 #pragma warning( disable : 4251 )
64 * Interface to a Shibboleth ServiceProvider instance.
66 * <p>A ServiceProvider exposes configuration and infrastructure services required
67 * by the SP implementation, allowing a flexible configuration format.
69 class SHIBSP_API ServiceProvider : public virtual xmltooling::Lockable, public virtual PropertySet
71 MAKE_NONCOPYABLE(ServiceProvider);
75 virtual ~ServiceProvider();
78 * Loads a configuration and prepares the instance for use.
80 * <p>Implemented as a separate method so that services can rely on
81 * other services while they initialize by accessing the ServiceProvider
82 * from the SPConfig singleton.
84 virtual void init()=0;
88 * Returns a TransactionLog instance.
90 * @return a TransactionLog instance
92 virtual TransactionLog* getTransactionLog() const=0;
95 * Returns a StorageService instance based on an ID.
97 * @param id a nullptr-terminated key identifying the StorageService to the configuration
98 * @return a StorageService if available, or nullptr
100 virtual xmltooling::StorageService* getStorageService(const char* id) const=0;
104 * Returns a SessionCache instance.
106 * @param required true iff an exception should be thrown if no SessionCache is available
107 * @return a SessionCache
109 virtual SessionCache* getSessionCache(bool required=true) const=0;
112 * Returns a ListenerService instance.
114 * @param required true iff an exception should be thrown if no ListenerService is available
115 * @return a ListenerService
117 virtual ListenerService* getListenerService(bool required=true) const=0;
121 * Returns a SecurityPolicyProvider instance.
123 * @param required true iff an exception should be thrown if no SecurityPolicyProvider is available
124 * @return a SecurityPolicyProvider
126 virtual SecurityPolicyProvider* getSecurityPolicyProvider(bool required=true) const;
130 * Returns the security policy settings for an identified policy.
132 * @param id identifies the policy to return, or nullptr for default
133 * @return a PropertySet
135 virtual const PropertySet* getPolicySettings(const char* id) const=0;
139 * Returns the security policy rules for an identified policy.
141 * @param id identifies the policy to return, or nullptr for default
142 * @return an array of policy rules
144 virtual const std::vector<const opensaml::SecurityPolicyRule*>& getPolicyRules(const char* id) const=0;
147 * Sets implementation-specific transport options.
149 * @param transport a SOAPTransport object
150 * @return true iff all options were successfully set
152 virtual bool setTransportOptions(xmltooling::SOAPTransport& transport) const=0;
156 * Returns a RequestMapper instance.
158 * @param required true iff an exception should be thrown if no RequestMapper is available
159 * @return a RequestMapper
161 virtual RequestMapper* getRequestMapper(bool required=true) const=0;
164 * Returns an Application instance matching the specified ID.
166 * @param applicationId the ID of the application, or nullptr for the default
167 * @return pointer to the application, or nullptr
169 virtual const Application* getApplication(const char* applicationId) const=0;
172 * Enforces requirements for an authenticated session.
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.
177 * @param request SP request interface
178 * @param handler true iff a request to a registered Handler location can be directly executed
179 * @return a pair containing a "request completed" indicator and a server-specific response code
181 virtual std::pair<bool,long> doAuthentication(SPRequest& request, bool handler=false) const;
184 * Enforces authorization requirements based on the authenticated session.
186 * <p>If the return value's first member is true, then request processing should terminate
187 * with the second member as a status value. If false, processing can continue.
189 * @param request SP request interface
190 * @return a pair containing a "request completed" indicator and a server-specific response code
192 virtual std::pair<bool,long> doAuthorization(SPRequest& request) const;
195 * Publishes session contents to the request in the form of headers or environment variables.
197 * <p>If the return value's first member is true, then request processing should terminate
198 * with the second member as a status value. If false, processing can continue.
200 * @param request SP request interface
201 * @param requireSession set to true iff an error should result if no session exists
202 * @return a pair containing a "request completed" indicator and a server-specific response code
204 virtual std::pair<bool,long> doExport(SPRequest& request, bool requireSession=true) const;
207 * Services requests for registered Handler locations.
209 * <p>If the return value's first member is true, then request processing should terminate
210 * with the second member as a status value. If false, processing can continue.
212 * @param request SP request interface
213 * @return a pair containing a "request completed" indicator and a server-specific response code
215 virtual std::pair<bool,long> doHandler(SPRequest& request) const;
218 * Register for a message. Returns existing remote service, allowing message hooking.
220 * @param address message address to register
221 * @param svc pointer to remote service
222 * @return previous service registered for message, if any
224 virtual Remoted* regListener(const char* address, Remoted* svc);
227 * Unregisters service from an address, possibly restoring an original.
229 * @param address message address to modify
230 * @param current pointer to unregistering service
231 * @param restore service to "restore" registration for
232 * @return true iff the current service was still registered
234 virtual bool unregListener(const char* address, Remoted* current, Remoted* restore=nullptr);
237 * Returns current service registered at an address, if any.
239 * @param address message address to access
240 * @return registered service, or nullptr
242 virtual Remoted* lookupListener(const char* address) const;
245 /** The AuthTypes to "recognize" (defaults to "shibboleth"). */
246 std::set<std::string> m_authTypes;
249 std::map<std::string,Remoted*> m_listenerMap;
252 #if defined (_MSC_VER)
253 #pragma warning( pop )
257 * Registers ServiceProvider classes into the runtime.
259 void SHIBSP_API registerServiceProviders();
261 /** SP based on integrated XML and native server configuration. */
262 #define XML_SERVICE_PROVIDER "XML"
265 #endif /* __shibsp_sp_h__ */