Support for Custom HTTP and SOAP Headers

Note: The content in this topic applies to Microsoft Office SharePoint Server 2007 SP1.

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. In Microsoft Office SharePoint Server 2007 SP1, the Business Data Catalog supports custom HTTP headers and SOAP headers for passing user name and password information to Web service calls.

HTTP Headers

The Business Data Catalog can send the user name and password stored in the Microsoft Single Sign-On (SSO) service application settings 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.

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

• Set the SecondarySSOAppID property of the LobSystemInstance element to the ID of the SSO enterprise application in Office SharePoint Server 2007 that contains the user name and password.

• 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

The Business Data Catalog can also send the user name and password stored in the SSO 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 sample. However, you should use SSL for the Web services that use this feature as the user name and password values are not encrypted.

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

• Set the SecondarySSOAppID property of the LobSystemInstance element with the ID of the SSO enterprise application in Office SharePoint Server 2007 that contains the user name and password.

• Set the following properties of the Method element:

  • SoapHeaderUserNameMemberName: The name of the user name SOAP header that the Web service understands.

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

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

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

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>

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, the Business Data Catalog generates a proxy. If the back-end Web method supports SOAP headers, the proxy that is generated looks like the following code example.

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; }
   }
}