saml/binding/MessageDecoder.h

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