2 * Copyright 2001-2006 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>
27 #include <xmltooling/signature/CredentialResolver.h>
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;
38 * Interface to a Shibboleth ServiceProvider instance.
40 * <p>A ServiceProvider exposes configuration and infrastructure services required
41 * by the SP implementation, allowing a flexible configuration format.
43 class SHIBSP_API ServiceProvider : public virtual xmltooling::Lockable, public virtual PropertySet
45 MAKE_NONCOPYABLE(ServiceProvider);
49 virtual ~ServiceProvider() {}
52 * Loads a configuration and prepares the instance for use.
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.
58 virtual void init()=0;
61 * Returns a SessionCache instance.
63 * @param required true iff an exception should be thrown if no SessionCache is available
64 * @return a SessionCache
66 virtual SessionCache* getSessionCache(bool required=true) const=0;
69 * Returns a ListenerService instance.
71 * @param required true iff an exception should be thrown if no ListenerService is available
72 * @return a ListenerService
74 virtual ListenerService* getListenerService(bool required=true) const=0;
77 * Returns a CredentialResolver instance mapped to a key.
79 * @param id a NULL-terminated key identifying the CredentialResolver to the configuration
80 * @return a CredentialResolver if available, or NULL
82 virtual xmlsignature::CredentialResolver* getCredentialResolver(const char* id) const=0;
85 * Returns a RequestMapper instance.
87 * @param required true iff an exception should be thrown if no RequestMapper is available
88 * @param a RequestMapper
90 virtual RequestMapper* getRequestMapper(bool required=true) const=0;
92 //virtual ISessionCache* getSessionCache() const=0;
95 * Returns an Application instance matching the specified ID.
97 * @param applicationId the ID of the application
98 * @return pointer to the application, or NULL
100 virtual const Application* getApplication(const char* applicationId) const=0;
103 * Enforces requirements for an authenticated session.
105 * <p>If the return value's first member is true, then request processing should terminate
106 * with the second member as a status value. If false, processing can continue.
108 * @param request SP request interface
109 * @param handler true iff a request to a registered Handler location can be directly executed
110 * @return a pair containing a "request completed" indicator and a server-specific response code
112 virtual std::pair<bool,long> doAuthentication(SPRequest& request, bool handler=false) const;
115 * Enforces authorization requirements based on the authenticated session.
117 * <p>If the return value's first member is true, then request processing should terminate
118 * with the second member as a status value. If false, processing can continue.
120 * @param request SP request interface
121 * @return a pair containing a "request completed" indicator and a server-specific response code
123 virtual std::pair<bool,long> doAuthorization(SPRequest& request) const;
126 * Publishes session contents to the request in the form of headers or environment variables.
128 * <p>If the return value's first member is true, then request processing should terminate
129 * with the second member as a status value. If false, processing can continue.
131 * @param request SP request interface
132 * @param requireSession set to true iff an error should result if no session exists
133 * @return a pair containing a "request completed" indicator and a server-specific response code
135 virtual std::pair<bool,long> doExport(SPRequest& request, bool requireSession=true) const;
138 * Services requests for registered Handler locations.
140 * <p>If the return value's first member is true, then request processing should terminate
141 * with the second member as a status value. If false, processing can continue.
143 * @param request SP request interface
144 * @return a pair containing a "request completed" indicator and a server-specific response code
146 virtual std::pair<bool,long> doHandler(SPRequest& request) const;
150 * Registers ServiceProvider classes into the runtime.
152 void SHIBSP_API registerServiceProviders();
154 /** SP based on integrated XML and native server configuration. */
155 #define XML_SERVICE_PROVIDER "edu.internet2.middleware.shibboleth.sp.provider.XMLServiceProvider"
158 #endif /* __shibsp_sp_h__ */