Support for Custom HTTP and SOAP Headers

  • Article

Applies to: SharePoint Server 2010

In this article
HTTP Headers
SOAP Headers
Custom SOAP Headers

With Web services, you can use HTTP headers or SOAP headers to provide application-specific information about the SOAP message; for example, you can provide authentication and payment information. BDC supports custom HTTP headers and SOAP headers for passing user name and password information to Web service calls.

HTTP Headers

BDC can send the user name and password stored in the Secure Store Provider as HTTP headers to Web service calls. The HTTP header values, that is, user name and password, are base 64 encoded. So in the Web service, you need to decode the values. Also you should use SSL for the Web services that use this feature as the user name and password values are not encrypted.

Note

The Web service binding should support the HTTP transport. Note that this is not a requirement for sending SOAP headers but only for sending HTTP headers.

To use HTTP headers, you must make the following changes in the application definition file:

  1. Set the SecondarySsoApplicationId property of the LobSystemInstance element to the Target Application ID of the Secure Store application that contains the user name and password.

  2. Set the HttpHeaderUserName and HttpHeaderPassword properties of the method with the respective header names that the Web service expects.

Example

<LobSystemInstance Name="ContosoInstance" DefaultDisplayName="SimpleHTTPInstance">
  <Properties>
    <Property Name="LobSystemName" Type="System.String">Contoso</Property> 
    <Property Name="AuthenticationMode" Type="System.String">WindowsCredentials</Property> 
     …
     …
    <Property Name="SecondarySsoApplicationId" Type="System.String">Contoso</Property> 
  </Properties>
</LobSystemInstance>
<Method Name="HelloWorld" DefaultDisplayName="HelloWorld">
     <Properties>
        <Property Name="HttpHeaderUserName" Type="System.String">UserName</Property>
         <Property Name="HttpHeaderPassword" Type="System.String">UserPassword</Property>
      </Properties>
      …
</Method>

SOAP Headers

BDC can also send the user name and password stored in the Secure Store settings as SOAP headers to Web service calls. The SOAP header values (user name and password) are not base 64 encoded. So in the Web service, you can read the values directly as shown in the following example. However, you should use SSL for the Web services that use this feature because the user name and password values are not encrypted.

To use SOAP headers, make the following changes in the application definition file:

  1. Set the SecondarySsoApplicationId property of the LobSystemInstance element with the Target Application ID of the Secure Store application that contains the user name and password.

  2. Set the following properties of the Method element:

    1. SoapHeaderUserNameMemberName: Name of the user name SOAP header that the Web service understands.

    2. SoapHeaderUserNameMemberFieldName: Name of the field that contains the user name.

    3. SoapHeaderPasswordMemberName: Name of the password SOAP header that the Web service understands.

    4. SoapHeaderPasswordMemberFieldName: Name of the field that contains the password.

Note

BDC also supports setting the user name and password in a single SOAP header. For SOAP headers that support both user name and password, the metadata property values for SoapHeaderUserNameMemberName and SoapHeaderPasswordMemberName are the same.

Example

<LobSystemInstance Name="ContosoInstance" DefaultDisplayName="SimpleSOAPInstance">
  <Properties>
    <Property Name="LobSystemName" Type="System.String">Contoso</Property> 
    <Property Name="AuthenticationMode" Type="System.String">WindowsCredentials</Property> 
     …
     …
    <Property Name="SecondarySsoApplicationId" Type="System.String">Contoso</Property> 
  </Properties>
</LobSystemInstance>
<Method Name="HelloWorld" DefaultDisplayName="HelloWorld">
   <Properties>
      <Property Name="SoapHeaderUserNameMemberName" Type="System.String">UserNameHeaderValue</Property>
      <Property Name="SoapHeaderUserNameMemberFieldName" Type="System.String">MyValue</Property>
      <Property Name="SoapHeaderPasswordMemberName" Type="System.String">UserPasswordHeaderValue</Property>
      <Property Name="SoapHeaderPasswordMemberFieldName" Type="System.String">MyValue</Property>
   </Properties>
  …
</Method>

Important

The Web server must support SOAP headers to be able to use them. In addition, you should add SOAP attribute to the Web method for each SOAP header. The follow code example shows this.

public class Service : System.Web.Services.WebService
{
    public UserNameHeader UserName;
    public UserPasswordHeader Password;

    public Service () { }
    [WebMethod]
    [SoapHeader("UserName", Direction=SoapHeaderDirection.In)]
    [SoapHeader("Password", Direction=SoapHeaderDirection.In)]
    public void HelloWorld() 
    {
        string password = "";
        string userName = "";
        if (UserName != null)
        {
            userName = UserName.MyValue;
        }
        if (Password != null)
        {
            password = Password.MyValue;
        }

        return null;
    }
}

public class UserNameHeader : SoapHeader
{
    public string MyValue;
}

public class UserPasswordHeader : SoapHeader
{
    public string MyValue;
}

As you know, to execute Web methods, BDC generates a proxy. If the back-end Web method supports SOAP headers, the proxy that is generated looks like the following code example.

Note

The following example shows only the relevant code.

public partial class Service : System.Web.Services.Protocols.SoapHttpClientProtocol
{
   private UserPasswordHeader userPasswordHeaderValueField;
   private UserNameHeader userNameHeaderValueField;

   public Service() {}

   public UserPasswordHeader UserPasswordHeaderValue
   {
      get { return this.userPasswordHeaderValueField;  }
      set { this.userPasswordHeaderValueField = value; }
   }

   public UserNameHeader UserNameHeaderValue
   {
      get { return this.userNameHeaderValueField;  }
      set { this.userNameHeaderValueField = value; }
   }

   public void HelloWorld()
   {
      object[] results = this.Invoke("HelloWorld", new object[0]);
      return (results[0]);
   }
}

public partial class UserPasswordHeader : System.Web.Services.Protocols.SoapHeader
{
   private string myValueField;

   public string MyValue
   {
      get { return this.myValueField;  }
      set { this.myValueField = value; }
   }
}

public partial class UserNameHeader : System.Web.Services.Protocols.SoapHeader
{
   private string myValueField;

   public string MyValue
   {
      get { return this.myValueField;  }
      set { this.myValueField = value; }
   }
}

Custom SOAP Headers

You can add custom SOAP headers with any stereotype method for a given LobSystemInstance. With custom SOAP headers, BDC will replace the username and password tokens with the values stored in the Secure Store. When custom SOAP headers are specified in the model, BDC does not verify that the Web service exposes these SOAP headers. Note that this behavior is in contrast to using SOAP headers where BDC requires the SOAP headers to be defined in the Web service.

To use custom SOAP headers, make the following changes in the application definition file:

  1. Set the SecondarySsoApplicationId property of the LobSystemInstance element with the Target Application ID of the Secure Store application that contains the user name and password.

  2. Add the SoapHeaderXml property to the LobSystemInstance element. The SoapHeaderXml property specifies to BDC that custom SOAP headers need to be sent to the Web service with every call.

    The contents of the SoapHeaderXml property consist of the username and password headers in the format that the Web service understands. The values of the username and password are represented by tokens that are later replaced by BDC when it retrieves these values from the Secure Store before sending the request to the Web service.

  3. Set the values of the Username and Password properties in the SoapHeaderXml property to the token to be replaced later by BDC.

  4. Set the value of the SoapHeaderXmlUserNameToken property to the token to replace for the user name value in the custom SOAP header.

  5. Set the value of the SoapHeaderXmlPasswordToken property to the token to replace for the password value in the custom SOAP header.

The following example shows these properties in the application definition file.

<LobSystemInstance Name="Lsi_WithCustomHeaders">
  <Properties>
    <Property Name="WcfAuthenticationMode" Type="System.String">PassThrough</Property>
    <Property Name="WcfEndpointAddress" Type="System.String"> WCF Endpoint Address </Property>
    <Property Name="SecondarySsoApplicationId" Type="System.String">Contoso</Property>
    <Property Name="SsoProviderImplementation" Type="System.String">Microsoft.Office.BusinessData.Infrastructure.SecureStore.LocalSecureStoreProvider, Microsoft.Office.BusinessData, Version=14.0.0.0, Culture=neutral, PublicKeyToken=94de0004b6e3fcc5</Property>
    <Property Name="SoapHeaderXml" Type="System.String">
      &lt;wsse:Security xmlns:wsse="https://schemas.xmlsoap.org/ws/2002/04/secext"&gt;
      &lt;wsse:UsernameToken&gt;
      &lt;wsse:Username&gt;CONTOSO_USERNAME_TOKEN&lt;/wsse:Username&gt;
      &lt;wsse:Password Type="wsse:PasswordText"&gt;CONTOSO_PASSWORD_TOKEN&lt;/wsse:Password&gt;
      &lt;/wsse:UsernameToken&gt;
      &lt;/wsse:Security&gt;
    </Property>
    <Property Name="SoapHeaderXmlUserNameToken" Type="System.String">CONTOSO_USERNAME_TOKEN</Property>
    <Property Name="SoapHeaderXmlPasswordToken" Type="System.String">CONTOSO_PASSWORD_TOKEN</Property>
  </Properties>
</LobSystemInstance>