saml/binding/MessageDecoder.h

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