2 * Licensed to the University Corporation for Advanced Internet
3 * Development, Inc. (UCAID) under one or more contributor license
4 * agreements. See the NOTICE file distributed with this work for
5 * additional information regarding copyright ownership.
7 * UCAID licenses this file to you under the Apache License,
8 * Version 2.0 (the "License"); you may not use this file except
9 * in compliance with the License. You may obtain a copy of the
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
17 * either express or implied. See the License for the specific
18 * language governing permissions and limitations under the License.
22 * @file shibsp/ServiceProvider.h
24 * Interface to a Shibboleth ServiceProvider instance.
27 #ifndef __shibsp_sp_h__
28 #define __shibsp_sp_h__
30 #include <shibsp/util/PropertySet.h>
34 #include <xmltooling/Lockable.h>
36 namespace xmltooling {
37 class XMLTOOL_API SOAPTransport;
38 class XMLTOOL_API StorageService;
43 class SAML_API SecurityPolicyRule;
49 class SHIBSP_API Application;
50 class SHIBSP_API Handler;
51 class SHIBSP_API ListenerService;
52 class SHIBSP_API Remoted;
53 class SHIBSP_API RequestMapper;
54 class SHIBSP_API SessionCache;
55 class SHIBSP_API SPRequest;
56 class SHIBSP_API TemplateParameters;
58 class SHIBSP_API SecurityPolicyProvider;
59 class SHIBSP_API TransactionLog;
62 #if defined (_MSC_VER)
63 #pragma warning( push )
64 #pragma warning( disable : 4251 )
68 * Interface to a Shibboleth ServiceProvider instance.
70 * <p>A ServiceProvider exposes configuration and infrastructure services required
71 * by the SP implementation, allowing a flexible configuration format.
73 class SHIBSP_API ServiceProvider : public virtual xmltooling::Lockable, public virtual PropertySet
75 MAKE_NONCOPYABLE(ServiceProvider);
79 virtual ~ServiceProvider();
82 * Loads a configuration and prepares the instance for use.
84 * <p>Implemented as a separate method so that services can rely on
85 * other services while they initialize by accessing the ServiceProvider
86 * from the SPConfig singleton.
88 virtual void init()=0;
92 * Returns a TransactionLog instance.
94 * @return a TransactionLog instance
96 virtual TransactionLog* getTransactionLog() const=0;
99 * Returns a StorageService instance based on an ID.
101 * @param id a nullptr-terminated key identifying the StorageService to the configuration
102 * @return a StorageService if available, or nullptr
104 virtual xmltooling::StorageService* getStorageService(const char* id) const=0;
108 * Returns a SessionCache instance.
110 * @param required true iff an exception should be thrown if no SessionCache is available
111 * @return a SessionCache
113 virtual SessionCache* getSessionCache(bool required=true) const=0;
116 * Returns a ListenerService instance.
118 * @param required true iff an exception should be thrown if no ListenerService is available
119 * @return a ListenerService
121 virtual ListenerService* getListenerService(bool required=true) const=0;
125 * Returns a SecurityPolicyProvider instance.
127 * @param required true iff an exception should be thrown if no SecurityPolicyProvider is available
128 * @return a SecurityPolicyProvider
130 virtual SecurityPolicyProvider* getSecurityPolicyProvider(bool required=true) const;
134 * Returns the security policy settings for an identified policy.
136 * @param id identifies the policy to return, or nullptr for default
137 * @return a PropertySet
139 virtual const PropertySet* getPolicySettings(const char* id) const=0;
143 * Returns the security policy rules for an identified policy.
145 * @param id identifies the policy to return, or nullptr for default
146 * @return an array of policy rules
148 virtual const std::vector<const opensaml::SecurityPolicyRule*>& getPolicyRules(const char* id) const=0;
151 * Sets implementation-specific transport options.
153 * @param transport a SOAPTransport object
154 * @return true iff all options were successfully set
156 virtual bool setTransportOptions(xmltooling::SOAPTransport& transport) const=0;
160 * Returns a RequestMapper instance.
162 * @param required true iff an exception should be thrown if no RequestMapper is available
163 * @return a RequestMapper
165 virtual RequestMapper* getRequestMapper(bool required=true) const=0;
168 * Returns an Application instance matching the specified ID.
170 * @param applicationId the ID of the application, or nullptr for the default
171 * @return pointer to the application, or nullptr
173 virtual const Application* getApplication(const char* applicationId) const=0;
176 * Enforces requirements for an authenticated session.
178 * <p>If the return value's first member is true, then request processing should terminate
179 * with the second member as a status value. If false, processing can continue.
181 * @param request SP request interface
182 * @param handler true iff a request to a registered Handler location can be directly executed
183 * @return a pair containing a "request completed" indicator and a server-specific response code
185 virtual std::pair<bool,long> doAuthentication(SPRequest& request, bool handler=false) const;
188 * Enforces authorization requirements based on the authenticated session.
190 * <p>If the return value's first member is true, then request processing should terminate
191 * with the second member as a status value. If false, processing can continue.
193 * @param request SP request interface
194 * @return a pair containing a "request completed" indicator and a server-specific response code
196 virtual std::pair<bool,long> doAuthorization(SPRequest& request) const;
199 * Publishes session contents to the request in the form of headers or environment variables.
201 * <p>If the return value's first member is true, then request processing should terminate
202 * with the second member as a status value. If false, processing can continue.
204 * @param request SP request interface
205 * @param requireSession set to true iff an error should result if no session exists
206 * @return a pair containing a "request completed" indicator and a server-specific response code
208 virtual std::pair<bool,long> doExport(SPRequest& request, bool requireSession=true) const;
211 * Services requests for registered Handler locations.
213 * <p>If the return value's first member is true, then request processing should terminate
214 * with the second member as a status value. If false, processing can continue.
216 * @param request SP request interface
217 * @return a pair containing a "request completed" indicator and a server-specific response code
219 virtual std::pair<bool,long> doHandler(SPRequest& request) const;
222 * Register for a message. Returns existing remote service, allowing message hooking.
224 * @param address message address to register
225 * @param svc pointer to remote service
226 * @return previous service registered for message, if any
228 virtual Remoted* regListener(const char* address, Remoted* svc);
231 * Unregisters service from an address, possibly restoring an original.
233 * @param address message address to modify
234 * @param current pointer to unregistering service
235 * @param restore service to "restore" registration for
236 * @return true iff the current service was still registered
238 virtual bool unregListener(const char* address, Remoted* current, Remoted* restore=nullptr);
241 * Returns current service registered at an address, if any.
243 * @param address message address to access
244 * @return registered service, or nullptr
246 virtual Remoted* lookupListener(const char* address) const;
249 /** The AuthTypes to "recognize" (defaults to "shibboleth"). */
250 std::set<std::string> m_authTypes;
253 std::map<std::string,Remoted*> m_listenerMap;
256 #if defined (_MSC_VER)
257 #pragma warning( pop )
261 * Registers ServiceProvider classes into the runtime.
263 void SHIBSP_API registerServiceProviders();
265 /** SP based on integrated XML and native server configuration. */
266 #define XML_SERVICE_PROVIDER "XML"
269 #endif /* __shibsp_sp_h__ */