saml/binding/MessageDecoder.h

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