saml/binding/MessageDecoder.h

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