Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท WS-Security and Standards

WS-Security: UsernameToken, Timestamps and Transport Security

Learn how WS-Security authenticates SOAP messages with UsernameToken, password digest, nonce and timestamp, when to rely on TLS instead, and how replay attacks are stopped.

A SOAP message may cross many hops: gateway, load balancer, message queue, audit service. TLS protects the connection between two neighbors, but it ends at each hop. WS-Security (WSS, an OASIS standard) puts security information inside the SOAP header, so protection travels with the message from the sender to the ultimate receiver. This lesson covers authentication with tokens; the next one covers signatures and encryption.

The Security header

All WS-Security content sits in one header block, wsse:Security, in the namespace http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd:

XML
<soap:Header>
  <wsse:Security soap:mustUnderstand="1"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsu:Timestamp wsu:Id="TS-1">
      <wsu:Created>2026-11-12T09:30:00Z</wsu:Created>
      <wsu:Expires>2026-11-12T09:35:00Z</wsu:Expires>
    </wsu:Timestamp>
    <wsse:UsernameToken wsu:Id="UT-1">
      <wsse:Username>ada</wsse:Username>
      <wsse:Password Type="...#PasswordDigest">dGhl...=</wsse:Password>
      <wsse:Nonce EncodingType="...#Base64Binary">MTIzNDU2Nzg5MDEyMzQ1Ng==</wsse:Nonce>
      <wsu:Created>2026-11-12T09:30:00Z</wsu:Created>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

The block is usually mustUnderstand="1": a service that cannot process it must reject the message rather than ignore the credentials. It can contain security tokens (username, X.509 certificate, SAML assertion, Kerberos ticket), a timestamp, signatures and encrypted data.

UsernameToken: three ways to send a password

Variant What is sent Safe?
PasswordText The password itself Only inside TLS. Anyone who sees the message learns the password.
PasswordDigest Base64(SHA-1(nonce + created + password)) The password is not sent, but SHA-1 and the server must know the clear password; still needs TLS in practice.
No password, signed instead A signature proves identity Preferred for high security; see the next lesson.

Digest works like this: the client creates a random nonce and a created time, computes SHA-1(nonce + created + password), and sends username, nonce, created and digest. The server looks up the password for the user, recomputes the digest and compares. An eavesdropper sees the digest but cannot reverse it. The weakness: the server must store the password in a recoverable form (or a password-equivalent), and SHA-1 is deprecated. That is why modern deployments use TLS plus PasswordText or tokens (SAML, JWT in a header) instead.

Computing a digest

Here is the exact computation. Because we fix the nonce and timestamp the output is the same every time; the server side recomputes and compares.

Node.js PasswordDigest, client and server

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The tampered case fails because created is part of the digested data: changing it changes the expected digest.

Replay attacks, nonces and timestamps

An attacker who records a valid message can send it again later. A digest alone does not stop that: the replayed digest is still correct. Two fields close the gap:

  • Timestamp window. The server rejects messages whose Created time is too old (or in the future), for example more than 5 minutes off its own clock. Clocks must be synchronized (NTP).
  • Nonce cache. The server remembers every nonce seen within the window and rejects a repeat.

Together: a replay inside the window is stopped by the nonce cache, and a replay after the window is stopped by the timestamp check, so the cache only has to hold nonces for the window length.

Node.js Blocking replayed messages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Timestamps on their own

Even without a username, a wsu:Timestamp in the Security header is useful: Created and Expires limit how long any signed message stays valid. Always include one, and sign it (next lesson), otherwise an attacker can edit it.

TLS or WS-Security?

TLS (HTTPS) WS-Security
Protects The connection, hop by hop The message itself, end to end
Survives intermediaries and queues no yes
Partial protection (sign one field, encrypt another) no yes
Setup effort small large
Interop headaches few many

Use TLS always. Add WS-Security when messages pass through intermediaries or queues you do not fully trust, when you need non-repudiation (a signature that proves who sent a document), or when a partner or regulation demands it.

Never send PasswordText over plain HTTP, never log full security headers (they hold credentials), and never skip the nonce and timestamp checks because "TLS is on". Replay and clock-skew bugs are common in real deployments.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which element of a SOAP message holds WS-Security data?

    WS-Security places tokens, timestamps, signatures and encrypted keys in the wsse:Security header block.
  2. 2. What is the purpose of the nonce in a UsernameToken?

    A unique random value per message lets the server detect a repeated (replayed) message.
  3. 3. Why does a replayed message with a correct digest still need to be rejected?

    An attacker who records a valid message can resend it. Nonce tracking and timestamp windows stop that.
  4. 4. When is WS-Security better than TLS alone?

    TLS protects only the hop; WS-Security protects the message itself end to end.
  5. 5. What does PasswordDigest hash?

    The digest is Base64(SHA-1(nonce + created + password)).

Summary

  • WS-Security puts security data in a wsse:Security header, so it travels with the message end to end.
  • UsernameToken can send the password as text or as a digest of nonce, created time and password.
  • Nonces and timestamps stop replay attacks; clocks must be in sync.
  • Use TLS always; add WS-Security for intermediaries, non-repudiation or partner requirements.
  • Never log credentials or send passwords over plain HTTP.

Next: WS-Security: Signatures and Encryption