saml/binding/MessageDecoder.h

   1 /*
   2  *  Copyright 2001-2006 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 <xmltooling/XMLObject.h>
  29
  30 namespace opensaml {
  31
  32     class SAML_API SAMLArtifact;
  33     class SAML_API X509TrustEngine;
  34     namespace saml1p {
  35         class SAML_API Response;
  36     };
  37     namespace saml2p {
  38         class SAML_API SAML2Artifact;
  39         class SAML_API ArtifactResponse;
  40     };
  41     namespace saml2md {
  42         class SAML_API MetadataProvider;
  43         class SAML_API IDPSSODescriptor;
  44         class SAML_API RoleDescriptor;
  45         class SAML_API SSODescriptorType;
  46     }
  47
  48     /**
  49      * Interface to SAML protocol binding message decoders.
  50      */
  51     class SAML_API MessageDecoder
  52     {
  53         MAKE_NONCOPYABLE(MessageDecoder);
  54     public:
  55         virtual ~MessageDecoder() {}
  56
  57         /**
  58          * Interface to caller-supplied shim for accessing HTTP request context.
  59          *
  60          * <p>To supply information from the surrounding web server environment,
  61          * a shim must be supplied in the form of this interface to adapt the
  62          * library to different proprietary server APIs.
  63          *
  64          * <p>This interface need not be threadsafe.
  65          */
  66         class SAML_API HTTPRequest {
  67             MAKE_NONCOPYABLE(HTTPRequest);
  68         protected:
  69             HTTPRequest() {}
  70         public:
  71             virtual ~HTTPRequest() {}
  72
  73             /**
  74              * Returns the HTTP method of the request (GET, POST, etc.)
  75              *
  76              * @return the HTTP method
  77              */
  78             virtual const char* getMethod() const=0;
  79
  80             /**
  81              * Returns the complete request URL, including scheme, host, port.
  82              *
  83              * @return the request URL
  84              */
  85             virtual const char* getRequestURL() const=0;
  86
  87             /**
  88              * Returns the HTTP query string appened to the request. The query
  89              * string is returned without any decoding applied, everything found
  90              * after the ? delimiter.
  91              *
  92              * @return the query string
  93              */
  94             virtual const char* getQueryString() const=0;
  95
  96             /**
  97              * Returns the raw HTTP request body. Used to access the body
  98              * of a POST that is not in URL-encoded form.
  99              *
 100              * @return the request body, or NULL
 101              */
 102             virtual const char* getRequestBody() const=0;
 103
 104             /**
 105              * Returns a decoded named parameter value from the query string or form body.
 106              * If a parameter has multiple values, only one will be returned.
 107              *
 108              * @param name  the name of the parameter to return
 109              * @return a single parameter value or NULL
 110              */
 111             virtual const char* getParameter(const char* name) const=0;
 112
 113             /**
 114              * Returns all of the decoded values of a named parameter from the query string
 115              * or form body. All values found will be returned.
 116              *
 117              * @param name      the name of the parameter to return
 118              * @param values    a vector in which to return pointers to the decoded values
 119              * @return  the number of values returned
 120              */
 121             virtual std::vector<const char*>::size_type getParameters(
 122                 const char* name, std::vector<const char*>& values
 123                 ) const=0;
 124
 125             /**
 126              * Returns the authenticated identity associated with the request
 127              *
 128              * @return the authenticated username or an empty string
 129              */
 130             virtual std::string getRemoteUser() const=0;
 131
 132             /**
 133              * Returns a request header value.
 134              *
 135              * @param name  the name of the header to return
 136              * @return the header's value, or an empty string
 137              */
 138             virtual std::string getHeader(const char* name) const=0;
 139         };
 140
 141         /**
 142          * Interface to caller-supplied artifact resolution mechanism.
 143          *
 144          * Resolving artifacts requires internally performing a SOAP-based
 145          * call to the artifact source, usually in a mutually authenticated fashion.
 146          * The potential options vary widely, so the work is encapsulated by this
 147          * interface, though of course other library facilities may be used.
 148          *
 149          * <p>A MessageDecoder implementation will invoke the supplied interface
 150          * when it requires an artifact be resolved.
 151          */
 152         class SAML_API ArtifactResolver {
 153             MAKE_NONCOPYABLE(ArtifactResolver);
 154         protected:
 155             ArtifactResolver() {}
 156
 157             /** Flag controlling schema validation. */
 158             bool m_validate;
 159
 160         public:
 161             virtual ~ArtifactResolver() {}
 162
 163             /**
 164              * Controls schema validation of incoming XML messages.
 165              * This is separate from other forms of programmatic validation of objects,
 166              * but can detect a much wider range of syntax errors.
 167              *
 168              * @param validate  true iff the resolver should use a validating XML parser
 169              */
 170             void setValidating(bool validate=true) {
 171                 m_validate = validate;
 172             }
 173
 174             /**
 175              * Resolves one or more SAML 1.x artifacts into a response containing a set of
 176              * resolved Assertions. The caller is responsible for the resulting Response.
 177              *
 178              * @param securityMech      will be set to identifier of security mechanism that authenticated the resolution
 179              * @param artifacts         one or more SAML 1.x artifacts
 180              * @param idpDescriptor     reference to IdP role of artifact issuer
 181              * @param trustEngine       optional pointer to X509TrustEngine supplied to MessageDecoder
 182              * @return the corresponding SAML Assertions wrapped in a Response.
 183              */
 184             virtual saml1p::Response* resolve(
 185                 const XMLCh*& securityMech,
 186                 const std::vector<SAMLArtifact*>& artifacts,
 187                 const saml2md::IDPSSODescriptor& idpDescriptor,
 188                 const X509TrustEngine* trustEngine=NULL
 189                 ) const=0;
 190
 191             /**
 192              * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
 193              * The caller is responsible for the resulting ArtifactResponse message.
 194              *
 195              * @param securityMech      will be set to identifier of security mechanism that authenticated the resolution
 196              * @param artifact          reference to a SAML 2.0 artifact
 197              * @param ssoDescriptor     reference to SSO role of artifact issuer (may be SP or IdP)
 198              * @param trustEngine       optional pointer to X509TrustEngine supplied to MessageDecoder
 199              * @return the corresponding SAML protocol message or NULL
 200              */
 201             virtual saml2p::ArtifactResponse* resolve(
 202                 const XMLCh*& securityMech,
 203                 const saml2p::SAML2Artifact& artifact,
 204                 const saml2md::SSODescriptorType& ssoDescriptor,
 205                 const X509TrustEngine* trustEngine=NULL
 206                 ) const=0;
 207         };
 208
 209         /**
 210          * Provides an ArtifactResolver implementation for the MessageDecoder to use.
 211          * The implementation's lifetime must be longer than the lifetime of this object.
 212          * This method must be externally synchronized.
 213          *
 214          * @param artifactResolver   an ArtifactResolver implementation to use
 215          */
 216         void setArtifactResolver(ArtifactResolver* artifactResolver) {
 217             m_artifactResolver = artifactResolver;
 218             if (m_artifactResolver)
 219                 m_artifactResolver->setValidating(m_validate);
 220         }
 221
 222         /**
 223          * Controls schema validation of incoming XML messages.
 224          * This is separate from other forms of programmatic validation of objects,
 225          * but can detect a much wider range of syntax errors.
 226          *
 227          * @param validate  true iff the decoder should use a validating XML parser
 228          */
 229         void setValidating(bool validate=true) {
 230             m_validate = validate;
 231             if (m_artifactResolver)
 232                 m_artifactResolver->setValidating(m_validate);
 233         }
 234
 235         /**
 236          * Decodes an HTTP request into a SAML protocol message, and returns related
 237          * information about the issuer of the message and whether it can be trusted.
 238          * If the HTTP request does not contain the information necessary to decode
 239          * the request, a NULL will be returned. Errors during the decoding process
 240          * will be raised as exceptions.
 241          *
 242          * <p>Artifact-based bindings require an ArtifactResolver be set to
 243          * turn an artifact into the corresponding message.
 244          *
 245          * <p>In some cases, a message may be returned but not authenticated. The caller
 246          * should examine the issuerTrusted output value to establish this.
 247          *
 248          * @param relayState        will be set to RelayState/TARGET value accompanying message
 249          * @param issuer            will be set to role descriptor of issuing party, if known
 250          * @param securityMech      will be set to identifier of security mechanism that authenticates the message
 251          * @param httpRequest       reference to interface for accessing HTTP message to decode
 252          * @param metadataProvider  optional MetadataProvider instance to authenticate the message
 253          * @param role              optional, identifies the role (generally IdP or SP) of the peer who issued the message
 254          * @param trustEngine       optional TrustEngine to authenticate the message
 255          * @return  the decoded message, or NULL if the decoder did not recognize the request content
 256          */
 257         virtual xmltooling::XMLObject* decode(
 258             std::string& relayState,
 259             const saml2md::RoleDescriptor*& issuer,
 260             const XMLCh*& securityMech,
 261             const HTTPRequest& httpRequest,
 262             const saml2md::MetadataProvider* metadataProvider=NULL,
 263             const xmltooling::QName* role=NULL,
 264             const TrustEngine* trustEngine=NULL
 265             ) const=0;
 266
 267     protected:
 268         MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {}
 269
 270         /** Pointer to an ArtifactResolver implementation. */
 271         ArtifactResolver* m_artifactResolver;
 272
 273         /** Flag controlling schema validation. */
 274         bool m_validate;
 275     };
 276
 277     /**
 278      * Registers MessageDecoder plugins into the runtime.
 279      */
 280     void SAML_API registerMessageDecoders();
 281 };
 282
 283 #endif /* __saml_decoder_h__ */