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