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/binding/GenericRequest.h>
27 #include <saml/binding/SecurityPolicy.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 artifact resolution mechanism.
60 * Resolving artifacts requires internally performing a SOAP-based
61 * call to the artifact source, usually in a mutually authenticated fashion.
62 * The potential options vary widely, so the work is encapsulated by this
63 * interface, though of course other library facilities may be used.
65 * <p>A MessageDecoder implementation will invoke the supplied interface
66 * when it requires an artifact be resolved.
68 class SAML_API ArtifactResolver {
69 MAKE_NONCOPYABLE(ArtifactResolver);
73 /** Flag controlling schema validation. */
77 virtual ~ArtifactResolver() {}
80 * Controls schema validation of incoming XML messages.
81 * This is separate from other forms of programmatic validation of objects,
82 * but can detect a much wider range of syntax errors.
84 * @param validate true iff the resolver should use a validating XML parser
86 void setValidating(bool validate=true) {
87 m_validate = validate;
91 * Resolves one or more SAML 1.x artifacts into a response containing a set of
92 * resolved Assertions. The caller is responsible for the resulting Response.
93 * The supplied SecurityPolicy is used to access caller-supplied infrastructure
94 * and to pass back the result of authenticating the resolution process.
96 * @param artifacts one or more SAML 1.x artifacts
97 * @param idpDescriptor reference to IdP role of artifact issuer
98 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
99 * @return the corresponding SAML Assertions wrapped in a Response.
101 virtual saml1p::Response* resolve(
102 const std::vector<SAMLArtifact*>& artifacts,
103 const saml2md::IDPSSODescriptor& idpDescriptor,
104 SecurityPolicy& policy
108 * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
109 * The caller is responsible for the resulting ArtifactResponse message.
110 * The supplied SecurityPolicy is used to access caller-supplied infrastructure
111 * and to pass back the result of authenticating the resolution process.
113 * @param artifact reference to a SAML 2.0 artifact
114 * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
115 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
116 * @return the corresponding SAML protocol message or NULL
118 virtual saml2p::ArtifactResponse* resolve(
119 const saml2p::SAML2Artifact& artifact,
120 const saml2md::SSODescriptorType& ssoDescriptor,
121 SecurityPolicy& policy
126 * Provides an ArtifactResolver implementation for the MessageDecoder to use.
127 * The implementation's lifetime must be longer than the lifetime of this object.
128 * This method must be externally synchronized.
130 * @param artifactResolver an ArtifactResolver implementation to use
132 void setArtifactResolver(ArtifactResolver* artifactResolver) {
133 m_artifactResolver = artifactResolver;
134 if (m_artifactResolver)
135 m_artifactResolver->setValidating(m_validate);
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 decoder should use a validating XML parser
145 void setValidating(bool validate=true) {
146 m_validate = validate;
147 if (m_artifactResolver)
148 m_artifactResolver->setValidating(m_validate);
152 * Decodes a transport request into a SAML protocol message, and evaluates it
153 * against a supplied SecurityPolicy. If the transport request does not contain
154 * the information necessary to decode the request, NULL will be returned.
155 * Errors during the decoding process will be raised as exceptions.
157 * <p>Artifact-based bindings require an ArtifactResolver be set to
158 * turn an artifact into the corresponding message.
160 * @param relayState will be set to RelayState/TARGET value accompanying message
161 * @param genericRequest reference to interface for accessing transport request to decode
162 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
163 * @return the decoded message, or NULL if the decoder did not recognize the request content
165 virtual xmltooling::XMLObject* decode(
166 std::string& relayState,
167 const GenericRequest& genericRequest,
168 SecurityPolicy& policy
172 MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {}
174 /** Pointer to an ArtifactResolver implementation. */
175 ArtifactResolver* m_artifactResolver;
177 /** Flag controlling schema validation. */
182 * Registers MessageDecoder plugins into the runtime.
184 void SAML_API registerMessageDecoders();
187 #endif /* __saml_decoder_h__ */