How to: Migrate Code that Secures a SOAP Message without Policy to Use Custom Policy Assertions

Article
09/13/2006

WSE 3.0 uses policy assertions to secure SOAP message exchanges between a client and Web services whether or not you are using a policy file. To migrate WSE 2.0 code that secured SOAP messages without using a policy file, migrate that code to a custom policy assertion. A custom policy assertion secures the SOAP message exchange between a client and a Web service. This SOAP message exchange comprises the following types of SOAP messages:

SOAP requests sent by the client.
SOAP requests received by the Web service.
SOAP responses sent by the Web service.
SOAP responses received by the client.

To secure these four types of SOAP messages, a policy assertion comprises four SOAP filters. So, to migrate WSE 2.0 code that secures SOAP messages to WSE 3.0, move that code into the corresponding SOAP filter for a policy assertion and then secure the SOAP message exchange using the policy assertion. The following steps detail where to move that code to. For more details about creating a custom policy assertion, see How to: Create a Custom Policy Assertion that Secures SOAP Messages. For more details about securing a SOAP message exchange, see How to: Secure a Web Service Using a Policy File.

For common application scenarios, WSE 3.0 introduces a set of turnkey security assertions that simplifies the process of securing these scenarios. For more details, see Turnkey Security Assertions.

To migrate code that secures a SOAP message to use custom policy assertions

Migrate WSE 2.0 client code that enforces security for outgoing SOAP messages to the SecureMessage method of a custom output filter that derives from the SendSecurityFilter class.

Use the Security argument that is passed into the SecureMessage method instead of the Security property of a SoapContext.

Note

To migrate WSE 2.0 code that uses the ExtendedSecurity property to add <Security> SOAP headers for additional SOAP actors, create an additional policy assertion for each additional actor. The ExtendedSecurity property does not exist in WSE 3.0.

The following code examples show how to move WSE 2.0 client code that enforces security for outgoing SOAP messages to a policy assertion in WSE 3.0.

WSE 2.0

Public Overrides Sub SecureMessage(ByVal envelope As SoapEnvelope, ByVal security As Security)
    Dim kerbToken As KerberosToken = _
        New KerberosToken("host/" + hostname & _
        "@" & domainName)

    ' Add the security token.                
    security.Tokens.Add(kerbToken)

    ' Specify the security token to sign the message with.
    Dim sig As New MessageSignature(kerbToken)
    security.Elements.Add(sig)
End Sub

public override void SecureMessage(SoapEnvelope envelope, Security security)
{
    KerberosToken kerbToken = new KerberosToken("host/" + hostname +
        "@" + domainName);

    // Add the security token.                
    security.Tokens.Add(kerbToken);

    // Specify the security token to sign the message with.
    MessageSignature sig = new MessageSignature(kerbToken);

    security.Elements.Add(sig);
}

WSE 3.0

Public Overrides Sub SecureMessage(ByVal envelope As SoapEnvelope, ByVal security As Security)
    Dim kerbToken As KerberosToken = _
        New KerberosToken("host/" + hostname & _
        "@" & domainName)

    ' Add the security token.                
    security.Tokens.Add(kerbToken)

    Dim sig As New MessageSignature(kerbToken)
    security.Elements.Add(sig)

End Sub 'SecureMessage

    public override void SecureMessage(SoapEnvelope envelope, Security security)
    {
        KerberosToken kerbToken = new KerberosToken("host/" + hostname +
"@" + domainName);

        // Add the security token.                
        security.Tokens.Add(kerbToken);

        // Specify the security token to sign the message with.
        MessageSignature sig = new MessageSignature(kerbToken);

        security.Elements.Add(sig);

    }

Migrate WSE 2.0 Web service code that verifies security for incoming SOAP messages to the ValidateMessageSecurity of a custom input filter that derives from the ReceiveSecurityFilter class.

Use the Security argument that is passed into the ValidateMessageSecurity method instead of the Security property of a SoapContext.

The following code examples show how to move WSE 2.0 Web service code that verifies security for incoming SOAP messages to a policy assertion in WSE 3.0.

WSE 2.0

WSE 3.0

Public Overrides Sub ValidateMessageSecurity(ByVal envelope As SoapEnvelope, ByVal security As Security)
    Dim element As ISecurityElement
    Dim isSigned As Boolean
    For Each element In security.Elements
        If (TypeOf element Is MessageSignature) Then
            ' The Security contains a digital signature element.
            Dim sign As MessageSignature = CType(element, MessageSignature)

            '  Verify the correct elements are signed.
            If ((sign.SignatureOptions And _
                (SignatureOptions.IncludeSoapBody Or _
                SignatureOptions.IncludeTo Or _
                SignatureOptions.IncludeAction Or _
                SignatureOptions.IncludeMessageId Or _
                SignatureOptions.IncludeFrom)) = _
                (SignatureOptions.IncludeSoapBody Or _
                SignatureOptions.IncludeTo Or _
                SignatureOptions.IncludeAction Or _
                SignatureOptions.IncludeMessageId Or _
                SignatureOptions.IncludeFrom)) Then
                ' Verify the SOAP message is signed by a KerberosToken.
                If (TypeOf sign.SigningToken Is KerberosToken) Then
                    ' The SOAP message is signed by a KerberosToken.
                    isSigned = True
                End If
            End If
        End If
    Next
    If (Not isSigned) Then
        Throw New Exception("Incoming message did not meet security requirements")
    End If
End Sub 'ValidateMessageSecurity

public override void ValidateMessageSecurity(SoapEnvelope envelope, Security security)
{
    bool isSigned = false;
    foreach (ISecurityElement element in security.Elements)
    {
        if (element is MessageSignature)
        {
            // The Security contains a digital signature element.
            MessageSignature sign = element as MessageSignature;

            // Verify the correct elements are signed.
            if ((sign.SignatureOptions &
                (SignatureOptions.IncludeSoapBody |
                SignatureOptions.IncludeTo |
                SignatureOptions.IncludeAction |
                SignatureOptions.IncludeMessageId |
                SignatureOptions.IncludeFrom)) ==
                (SignatureOptions.IncludeSoapBody |
                SignatureOptions.IncludeTo |
                SignatureOptions.IncludeAction |
                SignatureOptions.IncludeMessageId |
                SignatureOptions.IncludeFrom))
            {
                // Verify the SOAP message is signed by a KerberosToken.
                if (sign.SigningToken is KerberosToken)
                    // The SOAP message is signed by a KerberosToken.
                    isSigned = true;
            }
        }
    }
    if (!isSigned)
        throw new Exception("Incoming message did not meet security requirements");
}

Migrate WSE 2.0 Web service code that enforces security for outgoing SOAP messages to the SecureMessage method of a custom output filter.

Use the Security argument that is passed into the SecureMessage method instead of the Security property of a SoapContext.
Migrate WSE 2.0 client code that verifies security for incoming SOAP messages to the ValidateMessageSecurity of a custom input filter that derives from the ReceiveSecurityFilter class.

Use the Security argument that is passed into the ValidateMessageSecurity method instead of the Security property of a SoapContext.
Create a custom policy assertion that derives from the SecurityPolicyAssertion class.
Override the following four methods and set the return value for the methods to the previously created custom filters: CreateClientInputFilter, CreateClientOutputFilter, CreateServiceInputFilter, and CreateServiceOutputFilter.

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

Share via

How to: Migrate Code that Secures a SOAP Message without Policy to Use Custom Policy Assertions

To migrate code that secures a SOAP message to use custom policy assertions

See Also

Tasks

Concepts

Additional resources