2 * Licensed to the University Corporation for Advanced Internet
3 * Development, Inc. (UCAID) under one or more contributor license
4 * agreements. See the NOTICE file distributed with this work for
5 * additional information regarding copyright ownership.
7 * UCAID licenses this file to you under the Apache License,
8 * Version 2.0 (the "License"); you may not use this file except
9 * in compliance with the License. You may obtain a copy of the
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
17 * either express or implied. See the License for the specific
18 * language governing permissions and limitations under the License.
22 * @file saml/binding/MessageDecoder.h
24 * Interface to SAML protocol binding message decoders.
27 #ifndef __saml_decoder_h__
28 #define __saml_decoder_h__
30 #include <saml/base.h>
33 #include <xercesc/util/XMLUniDefs.hpp>
35 namespace xmltooling {
36 class XMLTOOL_API GenericRequest;
37 class XMLTOOL_API XMLObject;
42 class SAML_API SAMLArtifact;
43 class SAML_API SecurityPolicy;
45 class SAML_API Response;
48 class SAML_API SAML2Artifact;
49 class SAML_API ArtifactResponse;
52 class SAML_API MetadataProvider;
53 class SAML_API IDPSSODescriptor;
54 class SAML_API RoleDescriptor;
55 class SAML_API SSODescriptorType;
59 * Interface to SAML protocol binding message decoders.
61 class SAML_API MessageDecoder
63 MAKE_NONCOPYABLE(MessageDecoder);
65 virtual ~MessageDecoder();
68 * Returns identifier for the protocol family associated with the decoder.
70 * @return a protocol family identifier, or nullptr
72 virtual const XMLCh* getProtocolFamily() const;
75 * Indicates whether a web browser or similar user agent delivered the message.
77 * @return true iff the message was delivered by a user agent
79 virtual bool isUserAgentPresent() const;
82 * Interface to caller-supplied artifact resolution mechanism.
84 * Resolving artifacts requires internally performing a SOAP-based
85 * call to the artifact source, usually in a mutually authenticated fashion.
86 * The potential options vary widely, so the work is encapsulated by this
87 * interface, though of course other library facilities may be used.
89 * <p>A MessageDecoder implementation will invoke the supplied interface
90 * when it requires an artifact be resolved.
92 class SAML_API ArtifactResolver {
93 MAKE_NONCOPYABLE(ArtifactResolver);
98 virtual ~ArtifactResolver();
101 * Resolves one or more SAML 1.x artifacts into a response containing a set of
102 * resolved Assertions. The caller is responsible for the resulting Response.
103 * The supplied SecurityPolicy is used to access caller-supplied infrastructure
104 * and to pass back the result of authenticating the resolution process.
106 * @param artifacts one or more SAML 1.x artifacts
107 * @param idpDescriptor reference to IdP role of artifact issuer
108 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
109 * @return the corresponding SAML Assertions wrapped in a Response.
111 virtual saml1p::Response* resolve(
112 const std::vector<SAMLArtifact*>& artifacts,
113 const saml2md::IDPSSODescriptor& idpDescriptor,
114 SecurityPolicy& policy
118 * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
119 * The caller is responsible for the resulting ArtifactResponse message.
120 * The supplied SecurityPolicy is used to access caller-supplied infrastructure
121 * and to pass back the result of authenticating the resolution process.
123 * @param artifact reference to a SAML 2.0 artifact
124 * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
125 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
126 * @return the corresponding SAML protocol message or nullptr
128 virtual saml2p::ArtifactResponse* resolve(
129 const saml2p::SAML2Artifact& artifact,
130 const saml2md::SSODescriptorType& ssoDescriptor,
131 SecurityPolicy& policy
135 * Returns true iff the metadata provided includes a supported artifact resolution service.
137 * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
138 * @return true iff the artifact issuer offers endpoints supported by this resolver
140 virtual bool isSupported(const saml2md::SSODescriptorType& ssoDescriptor) const;
144 * Provides an ArtifactResolver implementation for the MessageDecoder to use.
145 * The implementation's lifetime must be longer than the lifetime of this object.
146 * This method must be externally synchronized.
148 * @param artifactResolver an ArtifactResolver implementation to use
150 void setArtifactResolver(const ArtifactResolver* artifactResolver);
153 * Decodes a transport request into a SAML protocol message, and evaluates it
154 * against a supplied SecurityPolicy. If the transport request does not contain
155 * the information necessary to decode the request, nullptr will be returned.
156 * Errors during the decoding process will be raised as exceptions.
158 * <p>Artifact-based bindings require an ArtifactResolver be set to
159 * turn an artifact into the corresponding message.
161 * @param relayState will be set to RelayState/TARGET value accompanying message
162 * @param genericRequest reference to interface for accessing transport request to decode
163 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
164 * @return the decoded message, or nullptr if the decoder did not recognize the request content
166 virtual xmltooling::XMLObject* decode(
167 std::string& relayState,
168 const xmltooling::GenericRequest& genericRequest,
169 SecurityPolicy& policy
175 /** Pointer to an ArtifactResolver implementation. */
176 const ArtifactResolver* m_artifactResolver;
179 * Extracts policy-relevant message details.
181 * @param message the incoming message
182 * @param request the protocol request
183 * @param protocol the protocol family in use
184 * @param policy SecurityPolicy to provide various components and track message data
186 virtual void extractMessageDetails (
187 const xmltooling::XMLObject& message,
188 const xmltooling::GenericRequest& request,
189 const XMLCh* protocol,
190 SecurityPolicy& policy
195 * Registers MessageDecoder plugins into the runtime.
197 void SAML_API registerMessageDecoders();
200 #endif /* __saml_decoder_h__ */