WS-Security Explained: Tokens, Signatures, Encryption

WS-Security (Web Services Security) is an OASIS standard designed to provide message-level security for SOAP-based web services, ensuring end-to-end data integrity, confidentiality, and authentication. Unlike transport-layer security (such as HTTPS) which only protects data in transit between direct endpoints, WS-Security embeds security mechanisms directly into the XML payload. This article explains the fundamentals of WS-Security and demonstrates how security tokens, digital signatures, and XML encryptions are structured and embedded within SOAP envelopes.

What is WS-Security?

WS-Security (WSS) defines a set of SOAP header extensions to implement secure web service communications. Because enterprise architectures often route SOAP messages through multiple intermediaries, proxies, or firewalls before reaching the final destination, transport-level security like TLS/HTTPS is insufficient. WS-Security solves this by attaching security metadata directly to the message, ensuring the payload remains secure and authentic across all intermediaries.

All WS-Security elements reside inside the standard SOAP <soap:Header> under a dedicated security element: <wsse:Security>.

Embedding Security Tokens

Security tokens authenticate the sender’s identity and convey claims or credentials to the receiving endpoint. WS-Security supports multiple token formats embedded inside the <wsse:Security> header:

  1. Username Tokens (<wsse:UsernameToken>): Basic credentials containing a username and either a plain text password, a hashed password with a digest, or a cryptographic nonce and timestamp.
  2. Binary Security Tokens (<wsse:BinarySecurityToken>): Encoded tokens such as X.509 public key certificates or Kerberos tickets, typically encoded in Base64.
  3. SAML Tokens (<saml:Assertion>): XML-based assertions containing identity, authorization, and attribute data for federated identity environments.

Example Structure:

<soap:Header>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken>
      <wsse:Username>service_user</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">dGVzdERpZ2VzdA==</wsse:Password>
      <wsse:Nonce>aW5wdXROb25jZQ==</wsse:Nonce>
      <wsu:Created xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2026-03-30T12:00:00Z</wsu:Created>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

Embedding XML Signatures

WS-Security leverages the W3C XML Signature standard to guarantee message integrity and non-repudiation. Signatures verify that specific parts of the message (such as the <soap:Body> or specific headers) have not been modified in transit.

The signature process involves: * Targeting Elements: Elements are identified using unique wsu:Id attributes. * Canonicalization and Digesting: The targeted XML is standardized (Canonical XML) and hashed. * Signing: The digest is encrypted using the sender’s private key and placed in a <ds:Signature> element inside the <wsse:Security> block. * Token Reference: A <wsse:SecurityTokenReference> links the signature to the corresponding public certificate (e.g., an X.509 token in the header) used for verification.

Example Structure:

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:SignedInfo>
    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
    <ds:Reference URI="#BodyID">
      <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
      <ds:DigestValue>eW91ckRpZ2VzdFZhbHVl</ds:DigestValue>
    </ds:Reference>
  </ds:SignedInfo>
  <ds:SignatureValue>c2lnbmF0dXJlRGF0YQ==</ds:SignatureValue>
  <ds:KeyInfo>
    <wsse:SecurityTokenReference>
      <wsse:Reference URI="#CertID" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
    </wsse:SecurityTokenReference>
  </ds:KeyInfo>
</ds:Signature>

Embedding XML Encryption

To ensure confidentiality, WS-Security utilizes the W3C XML Encryption standard. Instead of encrypting the entire transport stream, WS-Security allows targeted encryption of specific XML elements, such as sensitive payload data within the <soap:Body>.

The encryption process follows a hybrid cryptosystem: 1. Symmetric Encryption: The targeted XML content is encrypted using a fast symmetric key (e.g., AES-256). The plaintext XML is replaced in place with an <xenc:EncryptedData> element. 2. Asymmetric Key Wrapping: The symmetric key itself is encrypted using the recipient’s public key (e.g., RSA) and embedded as an <xenc:EncryptedKey> element inside the <wsse:Security> header. 3. Reference Lists: An <xenc:ReferenceList> within the <xenc:EncryptedKey> points to the <xenc:EncryptedData> elements that the key can decrypt.

Example Structure:

<!-- In the Header -->
<xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
  <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
  <xenc:CipherData>
    <xenc:CipherValue>ZW5jcnlwdGVkU3ltbWV0cmljS2V5</xenc:CipherValue>
  </xenc:CipherData>
  <xenc:ReferenceList>
    <xenc:DataReference URI="#EncryptedBodyContent"/>
  </xenc:ReferenceList>
</xenc:EncryptedKey>

<!-- In the Body -->
<soap:Body>
  <xenc:EncryptedData Id="EncryptedBodyContent" Type="http://www.w3.org/2001/04/xmlenc#Content">
    <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
    <xenc:CipherData>
      <xenc:CipherValue>Y2lwaGVydGV4dERhdGE=</xenc:CipherValue>
    </xenc:CipherData>
  </xenc:EncryptedData>
</soap:Body>

Summary of Operation

When combined, a secured SOAP message contains tokens for authentication, signatures for tamper detection, and encrypted elements for privacy. The receiver processes the <wsse:Security> header by validating the token, decrypting the symmetric key to read the encrypted data, and using the sender’s public key to verify signatures over the message contents.