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 * 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 class SAML_API HTTPRequest {
65 MAKE_NONCOPYABLE(HTTPRequest);
69 virtual ~HTTPRequest() {}
72 * Returns the HTTP method of the request (GET, POST, etc.)
74 * @return the HTTP method
76 virtual const char* getMethod() const=0;
79 * Returns the complete request URL, including scheme, host, port.
81 * @return the request URL
83 virtual const char* getRequestURL() const=0;
86 * Returns the HTTP query string appened to the request. The query
87 * string is returned without any decoding applied, everything found
88 * after the ? delimiter.
90 * @return the query string
92 virtual const char* getQueryString() const=0;
95 * Returns a decoded named parameter value from the query string or form body.
96 * If a parameter has multiple values, only one will be returned.
98 * @param name the name of the parameter to return
99 * @return a single parameter value or NULL
101 virtual const char* getParameter(const char* name) const=0;
104 * Returns all of the decoded values of a named parameter from the query string
105 * or form body. All values found will be returned.
107 * @param name the name of the parameter to return
108 * @param values a vector in which to return pointers to the decoded values
109 * @return the number of values returned
111 virtual std::vector<const char*>::size_type getParameters(
112 const char* name, std::vector<const char*>& values
117 * Interface to caller-supplied artifact resolution mechanism.
119 * Resolving artifacts requires internally performing a SOAP-based
120 * call to the artifact source, usually in a mutually authenticated fashion.
121 * The potential options vary widely, so the work is encapsulated by this
122 * interface, though of course other library facilities may be used.
124 * <p>A MessageDecoder implementation will invoke the supplied interface
125 * when it requires an artifact be resolved.
127 class SAML_API ArtifactResolver {
128 MAKE_NONCOPYABLE(ArtifactResolver);
130 ArtifactResolver() {}
132 /** Flag controlling schema validation. */
136 virtual ~ArtifactResolver() {}
139 * Controls schema validation of incoming XML messages.
140 * This is separate from other forms of programmatic validation of objects,
141 * but can detect a much wider range of syntax errors.
143 * @param validate true iff the resolver should use a validating XML parser
145 void setValidating(bool validate=true) {
146 m_validate = validate;
150 * Resolves one or more SAML 1.x artifacts into a response containing a set of
151 * resolved Assertions. The caller is responsible for the resulting Response.
153 * @param authenticated output flag set to true iff the resolution channel was authenticated
154 * @param artifacts one or more SAML 1.x artifacts
155 * @param idpDescriptor reference to IdP role of artifact issuer
156 * @param trustEngine optional pointer to X509TrustEngine supplied to MessageDecoder
157 * @return the corresponding SAML Assertions wrapped in a Response.
159 virtual saml1p::Response* resolve(
161 const std::vector<SAMLArtifact*>& artifacts,
162 const saml2md::IDPSSODescriptor& idpDescriptor,
163 const X509TrustEngine* trustEngine=NULL
167 * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
168 * The caller is responsible for the resulting ArtifactResponse message.
170 * @param authenticated output flag set to true iff the resolution channel was authenticated
171 * @param artifact reference to a SAML 2.0 artifact
172 * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
173 * @param trustEngine optional pointer to X509TrustEngine supplied to MessageDecoder
174 * @return the corresponding SAML protocol message or NULL
176 virtual saml2p::ArtifactResponse* resolve(
178 const saml2p::SAML2Artifact& artifact,
179 const saml2md::SSODescriptorType& ssoDescriptor,
180 const X509TrustEngine* trustEngine=NULL
185 * Provides an ArtifactResolver implementation for the MessageDecoder to use.
186 * The implementation's lifetime must be longer than the lifetime of this object.
187 * This method must be externally synchronized.
189 * @param artifactResolver an ArtifactResolver implementation to use
191 void setArtifactResolver(ArtifactResolver* artifactResolver) {
192 m_artifactResolver = artifactResolver;
193 if (m_artifactResolver)
194 m_artifactResolver->setValidating(m_validate);
198 * Controls schema validation of incoming XML messages.
199 * This is separate from other forms of programmatic validation of objects,
200 * but can detect a much wider range of syntax errors.
202 * @param validate true iff the decoder should use a validating XML parser
204 void setValidating(bool validate=true) {
205 m_validate = validate;
206 if (m_artifactResolver)
207 m_artifactResolver->setValidating(m_validate);
211 * Decodes an HTTP request into a SAML protocol message, and returns related
212 * information about the issuer of the message and whether it can be trusted.
213 * If the HTTP request does not contain the information necessary to decode
214 * the request, a NULL will be returned. Errors during the decoding process
215 * will be raised as exceptions.
217 * <p>Artifact-based bindings require an ArtifactResolver be set to
218 * turn an artifact into the corresponding message.
220 * <p>In some cases, a message may be returned but not authenticated. The caller
221 * should examine the issuerTrusted output value to establish this.
223 * @param relayState RelayState/TARGET value accompanying message
224 * @param issuer role descriptor of issuing party
225 * @param issuerTrusted output flag set to true iff the message was authenticated
226 * (signed or obtained via secure backchannel)
227 * @param httpRequest reference to interface for accessing HTTP message to decode
228 * @param metadataProvider optional MetadataProvider instance to authenticate the message
229 * @param role optional, identifies the role (generally IdP or SP) of the peer who issued the message
230 * @param trustEngine optional TrustEngine to authenticate the message
231 * @return the decoded message, or NULL if the decoder did not recognize the request content
233 virtual xmltooling::XMLObject* decode(
234 std::string& relayState,
235 const saml2md::RoleDescriptor*& issuer,
237 const HTTPRequest& httpRequest,
238 const saml2md::MetadataProvider* metadataProvider=NULL,
239 const xmltooling::QName* role=NULL,
240 const TrustEngine* trustEngine=NULL
244 MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {}
246 /** Pointer to an ArtifactResolver implementation. */
247 ArtifactResolver* m_artifactResolver;
249 /** Flag controlling schema validation. */
254 * Registers MessageDecoder plugins into the runtime.
256 void SAML_API registerMessageDecoders();
258 /** MessageDecoder for SAML 1.x Browser/Artifact "binding" (really part of profile) */
259 #define SAML1_ARTIFACT_DECODER "urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"
261 /** MessageDecoder for SAML 1.x Browser/POST "binding" (really part of profile) */
262 #define SAML1_POST_DECODER "urn:oasis:names:tc:SAML:1.0:profiles:browser-post"
264 /** MessageDecoder for SAML 2.0 HTTP-Artifact binding */
265 #define SAML2_ARTIFACT_DECODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
267 /** MessageDecoder for SAML 2.0 HTTP-POST binding */
268 #define SAML2_POST_DECODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
270 /** MessageDecoder for SAML 2.0 HTTP-Redirect binding */
271 #define SAML2_REDIRECT_DECODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
274 #endif /* __saml_decoder_h__ */