saml/binding/SOAPClient.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/SOAPClient.h
  23  *
  24  * Specialized SOAPClient for SAML SOAP bindings.
  25  */
  26
  27 #ifndef __saml_soap11client_h__
  28 #define __saml_soap11client_h__
  29
  30 #include <saml/base.h>
  31
  32 #include <xmltooling/soap/SOAPClient.h>
  33
  34 namespace opensaml {
  35
  36     class SAML_API SecurityPolicy;
  37     namespace saml2md {
  38         class SAML_API MetadataCredentialCriteria;
  39     };
  40
  41     /**
  42      * Specialized SOAPClient for SAML SOAP bindings.
  43      */
  44     class SAML_API SOAPClient : public soap11::SOAPClient
  45     {
  46     public:
  47         /**
  48          * Creates a SOAP client instance with a particular SecurityPolicy.
  49          *
  50          * @param policy        reference to SecurityPolicy to apply
  51          */
  52         SOAPClient(SecurityPolicy& policy);
  53
  54         virtual ~SOAPClient();
  55
  56         /**
  57          * Controls whether to force transport/peer authentication via an X509TrustEngine.
  58          *
  59          * <p>Only makes sense if an X509TrustEngine is supplied by the SecurityPolicy.
  60          *
  61          * @param force  true iff the client should refuse to communicate without this protection
  62          */
  63         void forceTransportAuthentication(bool force=true);
  64
  65         using soap11::SOAPClient::send;
  66
  67         /**
  68          * SAML-specific method uses metadata to determine the peer name and prepare the
  69          * transport layer with peer credential information. The SecurityPolicy is also reset,
  70          * in case the policy is reused.
  71          *
  72          * @param env       SOAP envelope to send
  73          * @param from      identity of sending application
  74          * @param to        peer to send message to, expressed in metadata criteria terms
  75          * @param endpoint  URL of endpoint to recieve message
  76          */
  77         virtual void send(const soap11::Envelope& env, const char* from, saml2md::MetadataCredentialCriteria& to, const char* endpoint);
  78
  79         /**
  80          * Override applies SecurityPolicy to envelope before returning it.
  81          *
  82          * @return response envelope after SecurityPolicy has been applied
  83          */
  84         soap11::Envelope* receive();
  85
  86         void reset();
  87
  88         /**
  89          * Returns the SecurityPolicy supplied to the client.
  90          *
  91          * @return  the associated SecurityPolicy
  92          */
  93         SecurityPolicy& getPolicy() const;
  94
  95     protected:
  96         /**
  97          * Override prepares transport by assigning an X509TrustEngine to it, if one is
  98          * attached to the policy.
  99          *
 100          * @param transport reference to transport layer
 101          */
 102         void prepareTransport(xmltooling::SOAPTransport& transport);
 103
 104         /** Reference to security policy to apply. */
 105         SecurityPolicy& m_policy;
 106
 107         /** Flag controlling whether transport/peer authn is mandatory. */
 108         bool m_force;
 109
 110         /** Metadata-based peer identity. */
 111         const saml2md::RoleDescriptor* m_peer;
 112
 113         /** Metadata-based CredentialCriteria for supplying credentials to TrustEngine. */
 114         saml2md::MetadataCredentialCriteria* m_criteria;
 115     };
 116
 117 };
 118
 119 #endif /* __saml_soap11client_h__ */