UsernameToken is a Web Service Security specification used to identify subjects by their username, and optionally authenticate the subject by verifying their proof of possession.

WSE 2.0 Implementation of UsernameToken

In the WSE implementation of UsernameToken, a password is used to establish proof of possession. The password sent in a UsernameToken message can be a cleartext password or a password equivalent, which is a unique representation of a password, typically created by hashing the cleartext password. A password can also be used by a requester to sign the message, which is then verified by a service. When a message is signed, the password used to sign the message is never included in the UsernameToken, as to do so would compromise the signature.

Once the message is received by the service, the AuthenticateToken method of the UsernameTokenManager class is used by WSE to validate the information in the UsernameToken. The AuthenticateToken method returns the password that was used for authentication. This return value is used by WSE to validate the original message. The specific type of validation is based on the password option that was used.

Note: AuthenticateToken can be overridden, allowing UsernameToken to be used in conjunction with custom Identity Providers. WSE 2.0 supports authenticating tokens based on a Windows user account with the password sent as plaintext (see options below). In all other cases a custom UsernameTokenManager is required.

WSE defines three password options used to send a password in the message: SendNone, SendPlainText and SendHashed.

SendNone

This option is used when signing the message with a digital signature. The password is never sent in the SOAP message, but WSE can use the password to sign the SOAP message. A recipient then needs to provide a password to WSE during the signature verification stage. This is accomplished by returning the password used to sign the message from the AuthenticateToken method.

SendPlainText

The password is always sent as plaintext in the SOAP message. This option is recommended only when the UsernameToken is encrypted using a security token or certificate obtained from the target Web service, or when a transport protocol such as SSL is used to connect to the Web service. Otherwise the password could be intercepted and compromised. WSE running on the recipient's computer compares the password in the SOAP message to the one returned from the AuthenticateToken method. If the two values are identical, the password is deemed valid.

SendHashed

The hash of the password is sent in the SOAP message. When a SOAP message is received with a UsernameToken, WSE calls the AuthenticateToken method of a custom UsernameTokenManager class, registered in the configuration file. The AuthenticateToken method returns a password or password equivalent, which WSE creates a hash from. That hash is compared to the one in the SOAP message and if they are identical, the hashed password is deemed valid.

The formula used to calculate the hash is: P_SHA1 ( password, label + nonce + created ) where:

• Password is either the real password or a password equivalent (for example the hash of the real password) represented as a UTF-8 string.
• Label is a shared string between sender and receiver, also a UTF-8 string. For the WSE 2.0 Tech Preview, this is the string "WS-Security".
• Nonce is "Number Once" material, a random sequence of bytes generated from a Cryptographic Random Number Generator (RNG), encoded as Base64.
• Created is the created time for the token specified in Zulu time using xsd:DateTime format, again encoded as a UTF-8 string.

In addition to verifying the hash, WSE also signs the message with HMAC-SHA1 using 16 bytes of key data from the hash keys.

Note: Although passwords are not sent as plaintext across the wire when the SendHashed option is used, they should be encrypted to prevent offline attacks. The SendHashed option is not recommended, if it results in passwords being stored in plaintext in the database.

References

WSE 2.0 Product Documentation at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wse/html/648af090-3ff0-415a-9967-ce37e8240070.asp

OASIS Standards and Other Approved Work (including WS-Security) at http://www.oasis-open.org/specs/index.php#wssv1.0

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