How to: Add Security Credentials to a SOAP Message

The Web Services Enhancements for Microsoft .NET (WSE) provides a mechanism for creating one or more security credentials that can be added to a SOAP message. Without using WSE, you can set the Credentials property of the proxy class, which enables the ultimate destination to authenticate the client application. However, if the SOAP message is routed through intermediaries before the ultimate destination, the client credentials might not flow to the ultimate destination, and thus the client is not authenticated. If you add the security credentials to the SOAP message using WSE, rather than at the transport layer using the proxy's Credentials property, the credentials can be routed through one or more intermediaries and still be validated at the ultimate destination.

The following procedure details how to add one or more security credentials to a SOAP message. For the following procedure to be successful, a computer must be set up to accept SOAP messages embedded with security credentials. The following table outlines the procedures for setting up a computer running WSE, to accept the security credentials.

Type of security credentials	Topic describing how to accept the credentials
X.509 certificate	How to: Verify Digital Signatures of SOAP Messages Signed by an X.509 Certificate
User name and password	How to: Verify Digital Signatures of SOAP Messages Signed Using a User Name and Password

Note

Adding a security token to a SOAP header does not provide any security in itself. To provide security, use the security token in conjunction with digital signing (using the MessageSignature class) or encryption (using the EncryptedData class).

To add a security token to a SOAP message

1. Open the Web service client project in Visual Studio .NET 2003.

2. Create a custom policy assertion.

   For more details about creating custom policy assertions, see How to: Create a Custom Policy Assertion that Secures SOAP Messages.

3. Add references to the Microsoft.Web.Services3 and System.Web.Services assemblies.

   1. On the Project menu, click Add Reference.
   2. On the .NET tab, select the component named Microsoft.Web.Services3.dll, and then click Select.
   3. On the .NET tab, select the component named System.Web.Services.dll, and then click Select.
   4. Click OK.

4. Add a Web Reference to the Web service that is to receive the SOAP message signed with the UsernameToken.

   1. On the Project menu, click Add Web Reference.
   2. In the Add Web Reference dialog box, type the URL for the Web service in the Address box, and then click the arrow icon.
   3. Verify that the items in the Available references box are the items you want to reference in your project, and then click Add Reference.

5. Add the following using directives to the top of the file containing the custom policy assertion:

   Imports Microsoft.VisualBasic
   
   Imports System
   Imports System.Collections.Generic
   Imports System.Text
   Imports System.Xml
   Imports System.Security.Cryptography.X509Certificates
   
   Imports Microsoft.Web.Services3
   Imports Microsoft.Web.Services3.Design
   Imports Microsoft.Web.Services3.Security
   Imports Microsoft.Web.Services3.Security.Tokens
   

   using System;
   using System.Collections.Generic;
   using System.Text;
   using System.Security.Cryptography.X509Certificates;
   
   using Microsoft.Web.Services3;
   using Microsoft.Web.Services3.Design;
   using Microsoft.Web.Services3.Security;
   using Microsoft.Web.Services3.Security.Tokens;
   

6. In the output SOAP filter for the client or the Web service that adds the security token to the SOAP message, override the SecureMessage method.

   The following code example overrides the SecureMessage method for the client output SOAP filter.

   Public Overrides Sub SecureMessage(ByVal envelope As SoapEnvelope, ByVal security As Security)
   

   public override void SecureMessage(SoapEnvelope envelope, Security security)
   {
   

7. Obtain the security token that you want to add to the SOAP message.

   The following code example creates an instance of the UsernameToken class.

   Dim userToken As UsernameToken
   userToken = New UsernameToken(userName, userName, PasswordOption.SendNone)
   

   UsernameToken userToken;
   userToken = new UsernameToken(userName, userPasswordEquivalent,
       PasswordOption.SendNone);
   

   Note

   It is recommended that a UsernameToken be sent with the PasswordOption set to SendPlainText.

8. Add the security token to the <Security> SOAP header.

   ' Adds the token to the SOAP header.
   security.Tokens.Add(userToken)
   

   // Adds the token to the SOAP header.
   security.Tokens.Add(userToken);
   

Example

The following code example adds a UsernameToken to a SOAP message.

Public Overrides Sub SecureMessage(ByVal envelope As SoapEnvelope, ByVal security As Security)
    Dim userToken As UsernameToken
    userToken = New UsernameToken(userName, userName, PasswordOption.SendNone)
    ' Adds the token to the SOAP header.
    security.Tokens.Add(userToken)
End Sub 'SecureMessage

public override void SecureMessage(SoapEnvelope envelope, Security security)
{
    UsernameToken userToken;
    userToken = new UsernameToken(userName, userPasswordEquivalent,
        PasswordOption.SendNone);
    // Adds the token to the SOAP header.
    security.Tokens.Add(userToken);
}

See Also

Other Resources

Advanced Security In WSE