Context

You are implementing Direct Authentication for an online application consuming a Web Service that uses Web Service Enhancements (WSE) 2.0. You are using Message layer authentication. The credentials, used to prove the identity of the calling application or user, are located in Active Directory or the Local Users identity store on the server.

Implementation Strategy

The WSE implementation of UsernameToken is used to implement Direct Authentication at the message layer. The requestor passes the subject's credentials to the Web service as part of a secure message exchange. A password is sent across the network, sent within the message as plaintext, because Active Directory requires that passwords are provided in plaintext format. The Web service decrypts the message, validates the credentials, verifies the message signature, and sends an encrypted response back to the requestor.

Approach

Two tasks must be performed to implement Direct Authentication with UsernameToken using Windows User Accounts.

1. Requestor generates Web service request.

2. Service authenticates Subject and returns a response.

Each task is divided into specific steps. While you are strongly encouraged to follow the recommendations, the steps contain enough information to allow you to tailor a solution to your specific needs.

Requestor Generates Web Service Request

This task has three steps that are recommended:

1. Initialize the UsernameToken

2. Establish message integrity

3. Encrypt the Message

Each step is discussed in more detail below:

Step One: Initialize UsernameToken

This pattern implements a UsernameToken with the SendPlainText password option, which sends the password over the network as plaintext. The “plaintext” value is the actual password because Active Directory requires plaintext passwords for credential validation. This option, used with the Default implementation of UsernameTokenManager, is similar to Basic Authentication over HTTP and as such should always be accompanied with SSL.

If the subject’s password is being sent in plaintext the session should always be encrypted.

Note: If you are not familiar with UsernameToken, refer to the UsernameToken Primer for more information.

The following code shows how to obtain a reference to the SOAP request context, initialize a UsernameToken and add it to the security tokens collection of the request context:

// obtain SOAP request context from Web service proxy

SoapContext requestContext = serviceProxy.RequestSoapContext;

UsernameToken token = new UsernameToken( txtUsername.Text, password, PasswordOption.SendPlainText );

requestContext.Security.Tokens.Add( token );

Step Two: Establish Message Integrity

An XML signature could be created to sign the request message to provide data integrity implicitly using Data Origin Authentication, but in this pattern, an XML signature is of no value. This is because the password used as the signing key must be included in the message. An attacker could tamper with the message and then create a new signature using the password as the signing key.

As the XML signature cannot be used to provide Data Origin Authentication, another approach must be used. In many cases, full DOA is not required, only data integrity. However, two approaches are available that can provide DOA to the requester (though not to the subject). These are:

• HTTPS
• WSE 2.0 using X509SecurityToken

HTTPS provides data confidentiality and data integrity when server certificates are used. If you require DOA to the requestor, you should also use a client certificate for the requestor. For more information, see Pattlet –Transport Layer Security using X.509 Certificates and HTTPS.

WSE 2.0 using X509SecurityToken only provides confidentiality without data integrity when server certificates are used. If you require DOA to the requestor, you should also implement client certificates. For more information, see Implementing Message Layer Security with X.509 Certificates in WSE 2.0.

Step Three: Encrypt the Message

You should encrypt the message from the requestor to the service to ensure that only the intended recipient of the message is capable of processing it. The same method chosen to provide DOA in the previous step should be used for Data Encryption.

HTTPS encrypts the request message from the Requestor so that only the Service can decrypt it. For details on implementing HTTPS, see “Pattlet –Transport Layer Security using X.509 Certificates and HTTPS”.

WSE 2.0 using X509SecurityToken uses the server’s X.509 certificate to encrypt the request message. Unlike SSL, parts of the message may be encrypted rather than the entire communication at the transport layer. For more information on implementing the alternate approach to SSL with message layer X.509 security, see Implementing Message Layer Security with X.509 Certificates in WSE 2.0.

If message layer X.509 encryption is being used, then code must be implemented to encrypt the message. For more information, and code examples that demonstrate how to encrypt the message, see Implementing Message Layer Security with X.509 Certificates in WSE 2.0.

Choosing Between HTTPS and WSE 2.0 using X509SecurityToken

When you implement Direct Authentication with UsernameToken using a Directory Service, you will need to ensure that you provide Data Confidentiality, and possibly DOA to the requestor.

HTTPSis a well-established protocol and is easy to implement on the Windows platform, requiring no additional code. However, there are circumstances when HTTPS is not an appropriate choice. If you need to persist messages, or if the messages must be handled by intermediaries, then you should use WSE 2.0 using X.509SecurityToken. Unlike HTTPS, parts of the message may be encrypted at the message layer, rather than the entire communication at the transport layer.

Service Authenticates Subject and Returns a Response

This task has four steps that are recommended:

1. Decrypt the request message

2. Verify message integrity

3. Validate the password

4. Encrypt the response

Each step is discussed in more detail below:

Step One: Decrypt the request message

The option chosen to encrypt the request message determines how the request message is decrypted by the Service. Both SSL and WSE 2.0 will encrypt the request message automatically, and require no additional coding.

Step Two: Verify Message Integrity

The method used when message integrity was established by the Requestor also defines the method used by the Service to verify message integrity. Both SSL and WSE (using an Integrity policy assertion) verify the message integrity automatically, and require no additional coding.

Step Three: UsernameToken manager validates password

Once the message is received by the service the information in UsernameToken is verified by WSE using the UsernameTokenManager class. The AuthenticateToken method of the UsernameTokenManager class, is used by WSE to validate the information in the UsernameToken.

Note: WSE 2.0 uses the UsernameTokenManager class to validate credentials presented in a UsernameToken by calling the winlogon API function. In Windows XP and Windows 2000, the service account, under which the web application validating the credentials is running, can only call the winlogon API if it has Log on Locally permissions to the server hosting the service.

The return value of AuthenticateToken is a password. This is used by WSE to verify the UsernameToken information by comparing it to the password that was sent in the message. The default UsernameTokenManager also establishes a WindowsPrincipal instance for the authenticated Subject and attaches it to the token’s Principal property.

Step Four: Encrypt the Response

The method used to encrypt the request message, is also used to encrypt the response message is encrypted by the Service. Both SSL and WSE 2.0 will encrypt the message response automatically, and require no additional coding.

Resulting Context

A number of benefits, liabilities, and security considerations are associated with this implementation of Direct Authentication, and are detailed in this section.

Benefits

WSE 2.0 authentication occurs against a Windows domain controller by default, without the need for Integrated Security on a Web server.

By using the existing Active Directory Infrastructure, you can minimize extra costs in establishing and migrating to a new authentication infrastructure. You also avoid having to synchronize Active Directory with another Identity Provider.

Liabilities

UsernameTokens in WSE prevent replay attacks under the covers by using a nonce and timestamp with a replay cache on the server. However, the replay cache is not shared across a server farm. Approaches to mitigate this issue include:

• Configuring a network load balancing device to allow session affinity, so that calling applications communicate with the same Web service throughout the duration of a session or replay cache lifetime. This is a relatively simple solution to the problem but sacrifices system availability. If the server hosting the Web service goes offline during a session, any state maintained by the Web service will be dropped, forcing the client to re-establish state on the server farm with a different server.
• Creating a common server-side state mechanism such as a central database cache to share the replay cache information across the server farm. While this solution minimally impacts availability of the server farm to calling applications, it is a more complex solution to implement, requiring extension of existing WSE classes to use the common state mechanism. One of the inherent problems with centralized state mechanisms is performance—since the state mechanism is farther away from the code implementation, it may affect performance. A database state mechanism is durable and sharable across multiple servers, but it is also much slower than an in-memory cache used by each server maintaining its own state.

Security Considerations

The following subjects represent security aspects that should be considered when using this implementation of Direct Authentication.

• The password in a UsernameToken should always be encrypted, using either message layer security, or transport layer security such as SSL. This mitigates the threat of an offline guessing attack against the UsernameToken.
• If SSL is implemented between several intermediaries providing point-to-point security, the environment is vulnerable to man-in-the-middle and XML attacks.

While passwords are considered one of the weakest forms of identity used for proof of possession, they are also the most common. As a result, it's important to understand threats and vulnerabilities associated with passwords.

• Passwords are often based on words and phrases that can be remembered, making it easier to discover passwords through the use of brute force attacks that try thousands of common passwords and word combinations. This vulnerability can be mitigated by using complex passwords or password phrases, although user passwords should still be memorable, or they are likely to be written down.

References

• Securing the Username Token with WSE 2.0 at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwse/html/securusernametoken.asp
• WS-Security at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

Microsoft Confidential. © 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement.