1 /** 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. 6 * 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 10 * License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 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. 19 */ 20 21 /** 22 * @file saml/binding/MessageDecoder.h 23 * 24 * Interface to SAML protocol binding message decoders. 25 */ 26 27 #ifndef __saml_decoder_h__ 28 #define __saml_decoder_h__ 29 30 #include <saml/base.h> 31 32 #include <vector> 33 #include <xercesc/util/XMLUniDefs.hpp> 34 35 namespace xmltooling { 36 class XMLTOOL_API GenericRequest; 37 class XMLTOOL_API GenericResponse; 38 class XMLTOOL_API XMLObject; 39 }; 40 41 namespace opensaml { 42 43 class SAML_API SAMLArtifact; 44 class SAML_API SecurityPolicy; 45 namespace saml1p { 46 class SAML_API Response; 47 }; 48 namespace saml2p { 49 class SAML_API SAML2Artifact; 50 class SAML_API ArtifactResponse; 51 }; 52 namespace saml2md { 53 class SAML_API MetadataProvider; 54 class SAML_API IDPSSODescriptor; 55 class SAML_API RoleDescriptor; 56 class SAML_API SSODescriptorType; 57 }; 58 59 /** 60 * Interface to SAML protocol binding message decoders. 61 */ 62 class SAML_API MessageDecoder 63 { 64 MAKE_NONCOPYABLE(MessageDecoder); 65 public: 66 virtual ~MessageDecoder(); 67 68 /** 69 * Returns identifier for the protocol family associated with the decoder. 70 * 71 * @return a protocol family identifier, or nullptr 72 */ 73 virtual const XMLCh* getProtocolFamily() const; 74 75 /** 76 * Indicates whether a web browser or similar user agent delivered the message. 77 * 78 * @return true iff the message was delivered by a user agent 79 */ 80 virtual bool isUserAgentPresent() const; 81 82 /** 83 * Interface to caller-supplied artifact resolution mechanism. 84 * 85 * Resolving artifacts requires internally performing a SOAP-based 86 * call to the artifact source, usually in a mutually authenticated fashion. 87 * The potential options vary widely, so the work is encapsulated by this 88 * interface, though of course other library facilities may be used. 89 * 90 * <p>A MessageDecoder implementation will invoke the supplied interface 91 * when it requires an artifact be resolved. 92 */ 93 class SAML_API ArtifactResolver { 94 MAKE_NONCOPYABLE(ArtifactResolver); 95 protected: 96 ArtifactResolver(); 97 98 public: 99 virtual ~ArtifactResolver(); 100 101 /** 102 * Resolves one or more SAML 1.x artifacts into a response containing a set of 103 * resolved Assertions. The caller is responsible for the resulting Response. 104 * The supplied SecurityPolicy is used to access caller-supplied infrastructure 105 * and to pass back the result of authenticating the resolution process. 106 * 107 * @param artifacts one or more SAML 1.x artifacts 108 * @param idpDescriptor reference to IdP role of artifact issuer 109 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc. 110 * @return the corresponding SAML Assertions wrapped in a Response. 111 */ 112 virtual saml1p::Response* resolve( 113 const std::vector<SAMLArtifact*>& artifacts, 114 const saml2md::IDPSSODescriptor& idpDescriptor, 115 SecurityPolicy& policy 116 ) const=0; 117 118 /** 119 * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message. 120 * The caller is responsible for the resulting ArtifactResponse message. 121 * The supplied SecurityPolicy is used to access caller-supplied infrastructure 122 * and to pass back the result of authenticating the resolution process. 123 * 124 * @param artifact reference to a SAML 2.0 artifact 125 * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP) 126 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc. 127 * @return the corresponding SAML protocol message or nullptr 128 */ 129 virtual saml2p::ArtifactResponse* resolve( 130 const saml2p::SAML2Artifact& artifact, 131 const saml2md::SSODescriptorType& ssoDescriptor, 132 SecurityPolicy& policy 133 ) const=0; 134 135 /** 136 * Returns true iff the metadata provided includes a supported artifact resolution service. 137 * 138 * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP) 139 * @return true iff the artifact issuer offers endpoints supported by this resolver 140 */ 141 virtual bool isSupported(const saml2md::SSODescriptorType& ssoDescriptor) const; 142 }; 143 144 /** 145 * Provides an ArtifactResolver implementation for the MessageDecoder to use. 146 * The implementation's lifetime must be longer than the lifetime of this object. 147 * This method must be externally synchronized. 148 * 149 * @param artifactResolver an ArtifactResolver implementation to use 150 */ 151 void setArtifactResolver(const ArtifactResolver* artifactResolver); 152 153 /** 154 * @Deprecated 155 * 156 * The future version is the variant below that also takes a response object. 157 * 158 * @param relayState will be set to RelayState/TARGET value accompanying message 159 * @param genericRequest reference to interface for accessing transport request to decode 160 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc. 161 * @return the decoded message, or nullptr if the decoder did not recognize the request content 162 */ 163 virtual xmltooling::XMLObject* decode( 164 std::string& relayState, 165 const xmltooling::GenericRequest& genericRequest, 166 SecurityPolicy& policy 167 ) const; 168 169 /** 170 * Decodes a transport request into a SAML protocol message, and evaluates it 171 * against a supplied SecurityPolicy. If the transport request does not contain 172 * the information necessary to decode the request, nullptr will be returned. 173 * Errors during the decoding process will be raised as exceptions. 174 * 175 * <p>Artifact-based bindings require an ArtifactResolver be set to 176 * turn an artifact into the corresponding message.</p> 177 * 178 * @param relayState will be set to RelayState/TARGET value accompanying message 179 * @param genericRequest reference to interface for accessing transport request to decode 180 * @param genericResponse optional interface for accessing transport response 181 * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc. 182 * @return the decoded message, or nullptr if the decoder did not recognize the request content 183 */ 184 virtual xmltooling::XMLObject* decode( 185 std::string& relayState, 186 const xmltooling::GenericRequest& genericRequest, 187 xmltooling::GenericResponse* genericResponse, 188 SecurityPolicy& policy 189 ) const; 190 191 protected: 192 MessageDecoder(); 193 194 /** Pointer to an ArtifactResolver implementation. */ 195 const ArtifactResolver* m_artifactResolver; 196 197 /** 198 * Extracts policy-relevant message details. 199 * 200 * @param message the incoming message 201 * @param request the protocol request 202 * @param protocol the protocol family in use 203 * @param policy SecurityPolicy to provide various components and track message data 204 */ 205 virtual void extractMessageDetails ( 206 const xmltooling::XMLObject& message, 207 const xmltooling::GenericRequest& request, 208 const XMLCh* protocol, 209 SecurityPolicy& policy 210 ) const=0; 211 }; 212 213 /** 214 * Registers MessageDecoder plugins into the runtime. 215 */ 216 void SAML_API registerMessageDecoders(); 217 }; 218 219 #endif /* __saml_decoder_h__ */ 220