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 saml/binding/MessageDecoder.h
20 * Interface to SAML protocol binding message decoders.
23 #ifndef __saml_decoder_h__
24 #define __saml_decoder_h__
26 #include <saml/base.h>
28 #include <xmltooling/XMLObject.h>
32 class SAML_API SAMLArtifact;
33 class SAML_API X509TrustEngine;
35 class SAML_API Response;
38 class SAML_API SAML2Artifact;
39 class SAML_API ArtifactResponse;
42 class SAML_API MetadataProvider;
43 class SAML_API IDPSSODescriptor;
44 class SAML_API RoleDescriptor;
45 class SAML_API SSODescriptorType;
49 * Interface to SAML protocol binding message decoders.
51 class SAML_API MessageDecoder
53 MAKE_NONCOPYABLE(MessageDecoder);
55 virtual ~MessageDecoder() {}
58 * Interface to caller-supplied shim for accessing HTTP request context.
60 * <p>To supply information from the surrounding web server environment,
61 * a shim must be supplied in the form of this interface to adapt the
62 * library to different proprietary server APIs.
64 * <p>This interface need not be threadsafe.
66 class SAML_API HTTPRequest {
67 MAKE_NONCOPYABLE(HTTPRequest);
71 virtual ~HTTPRequest() {}
74 * Returns the HTTP method of the request (GET, POST, etc.)
76 * @return the HTTP method
78 virtual const char* getMethod() const=0;
81 * Returns the complete request URL, including scheme, host, port.
83 * @return the request URL
85 virtual const char* getRequestURL() const=0;
88 * Returns the HTTP query string appened to the request. The query
89 * string is returned without any decoding applied, everything found
90 * after the ? delimiter.
92 * @return the query string
94 virtual const char* getQueryString() const=0;
97 * Returns the raw HTTP request body. Used to access the body
98 * of a POST that is not in URL-encoded form.
100 * @return the request body, or NULL
102 virtual const char* getRequestBody() const=0;
105 * Returns a decoded named parameter value from the query string or form body.
106 * If a parameter has multiple values, only one will be returned.
108 * @param name the name of the parameter to return
109 * @return a single parameter value or NULL
111 virtual const char* getParameter(const char* name) const=0;
114 * Returns all of the decoded values of a named parameter from the query string
115 * or form body. All values found will be returned.
117 * @param name the name of the parameter to return
118 * @param values a vector in which to return pointers to the decoded values
119 * @return the number of values returned
121 virtual std::vector<const char*>::size_type getParameters(
122 const char* name, std::vector<const char*>& values
126 * Returns the authenticated identity associated with the request
128 * @return the authenticated username or an empty string
130 virtual std::string getRemoteUser() const=0;
133 * Returns a request header value.
135 * @param name the name of the header to return
136 * @return the header's value, or an empty string
138 virtual std::string getHeader(const char* name) const=0;
142 * Interface to caller-supplied artifact resolution mechanism.
144 * Resolving artifacts requires internally performing a SOAP-based
145 * call to the artifact source, usually in a mutually authenticated fashion.
146 * The potential options vary widely, so the work is encapsulated by this
147 * interface, though of course other library facilities may be used.
149 * <p>A MessageDecoder implementation will invoke the supplied interface
150 * when it requires an artifact be resolved.
152 class SAML_API ArtifactResolver {
153 MAKE_NONCOPYABLE(ArtifactResolver);
155 ArtifactResolver() {}
157 /** Flag controlling schema validation. */
161 virtual ~ArtifactResolver() {}
164 * Controls schema validation of incoming XML messages.
165 * This is separate from other forms of programmatic validation of objects,
166 * but can detect a much wider range of syntax errors.
168 * @param validate true iff the resolver should use a validating XML parser
170 void setValidating(bool validate=true) {
171 m_validate = validate;
175 * Resolves one or more SAML 1.x artifacts into a response containing a set of
176 * resolved Assertions. The caller is responsible for the resulting Response.
178 * @param securityMech will be set to identifier of security mechanism that authenticated the resolution
179 * @param artifacts one or more SAML 1.x artifacts
180 * @param idpDescriptor reference to IdP role of artifact issuer
181 * @param trustEngine optional pointer to X509TrustEngine supplied to MessageDecoder
182 * @return the corresponding SAML Assertions wrapped in a Response.
184 virtual saml1p::Response* resolve(
185 const XMLCh*& securityMech,
186 const std::vector<SAMLArtifact*>& artifacts,
187 const saml2md::IDPSSODescriptor& idpDescriptor,
188 const X509TrustEngine* trustEngine=NULL
192 * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
193 * The caller is responsible for the resulting ArtifactResponse message.
195 * @param securityMech will be set to identifier of security mechanism that authenticated the resolution
196 * @param artifact reference to a SAML 2.0 artifact
197 * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
198 * @param trustEngine optional pointer to X509TrustEngine supplied to MessageDecoder
199 * @return the corresponding SAML protocol message or NULL
201 virtual saml2p::ArtifactResponse* resolve(
202 const XMLCh*& securityMech,
203 const saml2p::SAML2Artifact& artifact,
204 const saml2md::SSODescriptorType& ssoDescriptor,
205 const X509TrustEngine* trustEngine=NULL
210 * Provides an ArtifactResolver implementation for the MessageDecoder to use.
211 * The implementation's lifetime must be longer than the lifetime of this object.
212 * This method must be externally synchronized.
214 * @param artifactResolver an ArtifactResolver implementation to use
216 void setArtifactResolver(ArtifactResolver* artifactResolver) {
217 m_artifactResolver = artifactResolver;
218 if (m_artifactResolver)
219 m_artifactResolver->setValidating(m_validate);
223 * Controls schema validation of incoming XML messages.
224 * This is separate from other forms of programmatic validation of objects,
225 * but can detect a much wider range of syntax errors.
227 * @param validate true iff the decoder should use a validating XML parser
229 void setValidating(bool validate=true) {
230 m_validate = validate;
231 if (m_artifactResolver)
232 m_artifactResolver->setValidating(m_validate);
236 * Decodes an HTTP request into a SAML protocol message, and returns related
237 * information about the issuer of the message and whether it can be trusted.
238 * If the HTTP request does not contain the information necessary to decode
239 * the request, a NULL will be returned. Errors during the decoding process
240 * will be raised as exceptions.
242 * <p>Artifact-based bindings require an ArtifactResolver be set to
243 * turn an artifact into the corresponding message.
245 * <p>In some cases, a message may be returned but not authenticated. The caller
246 * should examine the issuerTrusted output value to establish this.
248 * @param relayState will be set to RelayState/TARGET value accompanying message
249 * @param issuer will be set to role descriptor of issuing party, if known
250 * @param securityMech will be set to identifier of security mechanism that authenticates the message
251 * @param httpRequest reference to interface for accessing HTTP message to decode
252 * @param metadataProvider optional MetadataProvider instance to authenticate the message
253 * @param role optional, identifies the role (generally IdP or SP) of the peer who issued the message
254 * @param trustEngine optional TrustEngine to authenticate the message
255 * @return the decoded message, or NULL if the decoder did not recognize the request content
257 virtual xmltooling::XMLObject* decode(
258 std::string& relayState,
259 const saml2md::RoleDescriptor*& issuer,
260 const XMLCh*& securityMech,
261 const HTTPRequest& httpRequest,
262 const saml2md::MetadataProvider* metadataProvider=NULL,
263 const xmltooling::QName* role=NULL,
264 const TrustEngine* trustEngine=NULL
268 MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {}
270 /** Pointer to an ArtifactResolver implementation. */
271 ArtifactResolver* m_artifactResolver;
273 /** Flag controlling schema validation. */
278 * Registers MessageDecoder plugins into the runtime.
280 void SAML_API registerMessageDecoders();
283 #endif /* __saml_decoder_h__ */