2 * Copyright 2001-2007 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>
28 # include <saml/binding/SecurityPolicyRule.h>
29 # include <xmltooling/soap/SOAPTransport.h>
30 # include <xmltooling/util/StorageService.h>
32 #include <xmltooling/Lockable.h>
36 class SHIBSP_API Application;
37 class SHIBSP_API Handler;
38 class SHIBSP_API ListenerService;
39 class SHIBSP_API RequestMapper;
40 class SHIBSP_API SessionCache;
41 class SHIBSP_API SPRequest;
42 class SHIBSP_API TemplateParameters;
44 class SHIBSP_API TransactionLog;
48 * Interface to a Shibboleth ServiceProvider instance.
50 * <p>A ServiceProvider exposes configuration and infrastructure services required
51 * by the SP implementation, allowing a flexible configuration format.
53 class SHIBSP_API ServiceProvider : public virtual xmltooling::Lockable, public virtual PropertySet
55 MAKE_NONCOPYABLE(ServiceProvider);
59 virtual ~ServiceProvider() {}
62 * Loads a configuration and prepares the instance for use.
64 * <p>Implemented as a separate method so that services can rely on
65 * other services while they initialize by accessing the ServiceProvider
66 * from the SPConfig singleton.
68 virtual void init()=0;
72 * Returns a TransactionLog instance.
74 * @return a TransactionLog instance
76 virtual TransactionLog* getTransactionLog() const=0;
79 * Returns a StorageService instance based on an ID.
81 * @param id a NULL-terminated key identifying the StorageService to the configuration
82 * @return a StorageService if available, or NULL
84 virtual xmltooling::StorageService* getStorageService(const char* id) const=0;
88 * Returns a SessionCache instance.
90 * @param required true iff an exception should be thrown if no SessionCache is available
91 * @return a SessionCache
93 virtual SessionCache* getSessionCache(bool required=true) const=0;
96 * Returns a ListenerService instance.
98 * @param required true iff an exception should be thrown if no ListenerService is available
99 * @return a ListenerService
101 virtual ListenerService* getListenerService(bool required=true) const=0;
105 * Returns the security policy settings for an identified policy.
107 * @param id identifies the policy to return
108 * @return a PropertySet
110 virtual const PropertySet* getPolicySettings(const char* id) const=0;
113 * Returns the security policy rules for an identified policy.
115 * @param id identifies the policy to return
116 * @return an array of policy rules
118 virtual const std::vector<const opensaml::SecurityPolicyRule*>& getPolicyRules(const char* id) const=0;
121 * Sets implementation-specific transport options.
123 * @param transport a SOAPTransport object
124 * @return true iff all options were successfully set
126 virtual bool setTransportOptions(xmltooling::SOAPTransport& transport) const=0;
130 * Returns a RequestMapper instance.
132 * @param required true iff an exception should be thrown if no RequestMapper is available
133 * @return a RequestMapper
135 virtual RequestMapper* getRequestMapper(bool required=true) const=0;
138 * Returns an Application instance matching the specified ID.
140 * @param applicationId the ID of the application
141 * @return pointer to the application, or NULL
143 virtual const Application* getApplication(const char* applicationId) const=0;
146 * Enforces requirements for an authenticated session.
148 * <p>If the return value's first member is true, then request processing should terminate
149 * with the second member as a status value. If false, processing can continue.
151 * @param request SP request interface
152 * @param handler true iff a request to a registered Handler location can be directly executed
153 * @return a pair containing a "request completed" indicator and a server-specific response code
155 virtual std::pair<bool,long> doAuthentication(SPRequest& request, bool handler=false) const;
158 * Enforces authorization requirements based on the authenticated session.
160 * <p>If the return value's first member is true, then request processing should terminate
161 * with the second member as a status value. If false, processing can continue.
163 * @param request SP request interface
164 * @return a pair containing a "request completed" indicator and a server-specific response code
166 virtual std::pair<bool,long> doAuthorization(SPRequest& request) const;
169 * Publishes session contents to the request in the form of headers or environment variables.
171 * <p>If the return value's first member is true, then request processing should terminate
172 * with the second member as a status value. If false, processing can continue.
174 * @param request SP request interface
175 * @param requireSession set to true iff an error should result if no session exists
176 * @return a pair containing a "request completed" indicator and a server-specific response code
178 virtual std::pair<bool,long> doExport(SPRequest& request, bool requireSession=true) const;
181 * Services requests for registered Handler locations.
183 * <p>If the return value's first member is true, then request processing should terminate
184 * with the second member as a status value. If false, processing can continue.
186 * @param request SP request interface
187 * @return a pair containing a "request completed" indicator and a server-specific response code
189 virtual std::pair<bool,long> doHandler(SPRequest& request) const;
193 * Registers ServiceProvider classes into the runtime.
195 void SHIBSP_API registerServiceProviders();
197 /** SP based on integrated XML and native server configuration. */
198 #define XML_SERVICE_PROVIDER "XML"
201 #endif /* __shibsp_sp_h__ */