UsernameToken

UsernameToken is a security token defined by WS-Security used to convey a user's credentials in a message-based web service. It enables a client to authenticate to a service by presenting a username and either a password or a password-derived value within the SOAP message header, rather than through an out-of-band mechanism.

In a typical SOAP exchange, the UsernameToken is placed inside the WS-Security header of the SOAP envelope. The token consists of elements such as Username, and Password. The Password element carries either the plaintext password (type PasswordText) or a password digest (type PasswordDigest). When using a digest, the server verifies the password by recomputing the digest from the shared password, a nonce, and a timestamp action Created. A Nonce element provides a random value, encoded in base64, to help prevent replay attacks. Created records the time the password or digest was generated, typically in ISO 8601 format.

Usage considerations: UsernameToken is commonly used with SOAP-based web services and WS-Security profiles. It is typically transported over HTTPS to protect credentials in transit. If PasswordDigest is used, the token provides some protection against eavesdropping, but TLS is still recommended. Some deployments require the MustUnderstand attribute on the Security header to ensure the token is processed by the recipient.

Interoperability and variants: UsernameToken is part of WS-Security standards and may be combined with other tokens or extended profiles, such as signing or encryption. Not all systems support all forms; some services may prefer other authentication methods like SAML or OAuth.

Security notes: avoid logging plaintext passwords; synchronize clocks to validate Created timestamps; ensure nonce is unique per request; implement replay protection and proper error handling.