WS-Security — Authentication and Encryption for SOAP Web Services

In this tutorial, you will learn about WS. We cover key concepts, practical examples, and best practices to help you master this topic.

WS-Security (Web Services Security) is a SOAP extension that provides message-level security including authentication tokens, XML digital signatures for integrity, and XML encryption for confidentiality.

What You'll Learn

• WS-Security token types (UsernameToken, X.509, SAML)
• XML Signature for message integrity
• XML Encryption for confidentiality

Why It Matters

WS-Security provides end-to-end security that survives intermediaries, unlike transport-level security (HTTPS) which only protects point-to-point.

Code Examples

<!-- WS-Security UsernameToken -->
<soap:Header>
  <wsse:Security
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken wsu:Id="Token-1">
      <wsse:Username>admin</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">
        base64encodedhash
      </wsse:Password>
      <wsse:Nonce>base64nonce</wsse:Nonce>
      <wsu:Created>2024-01-15T10:30:00Z</wsu:Created>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

# WS-Security with zeep (Python)
from zeep import Client
from zeep.wsse.username import UsernameToken

client = Client(
    'http://example.com/secure/service?wsdl',
    wsse=UsernameToken('admin', 'secret123', use_digest=True)
)

# All subsequent calls include WS-Security headers
result = client.service.GetSecureData(ID=123)

<!-- XML Signature in WS-Security -->
<wsse:Security>
  <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="#Body">
        <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <ds:DigestValue>base64digest...</ds:DigestValue>
      </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>base64signature...</ds:SignatureValue>
  </ds:Signature>
</wsse:Security>

Common Mistakes

1. Relying Only on Transport Security

HTTPS protects point-to-point. WS-Security protects message-level end-to-end.

2. Using Plain Text Passwords

Use PasswordDigest instead of PasswordText in production.

3. Forgetting Nonce and Created

These prevent replay attacks. Required for secure password digest.

4. Not Signing the Body

Signatures should cover the Body and relevant headers to prevent tampering.

5. Confusing WS-Security with HTTPS

They complement each other. Use both for defense in depth.

Practice Questions

1. What three security functions does WS-Security provide?
2. What is the difference between PasswordText and PasswordDigest?
3. Why does WS-Security use Nonce and Created timestamps?
4. How does WS-Security differ from HTTPS?
5. What token types does WS-Security support?

Answers:

1. Authentication (tokens), integrity (signatures), confidentiality (encryption).
2. PasswordText sends the password in clear text; PasswordDigest sends a hash.
3. To prevent replay attacks where an attacker resends captured messages.
4. WS-Security is message-level (end-to-end); HTTPS is transport-level (point-to-point).
5. UsernameToken, X.509 certificates, SAML assertions, Kerberos tickets.

Challenge: Create a WS-Security configuration that uses an X.509 certificate to sign the SOAP Body and encrypt sensitive data fields.

FAQ

What's Next

Compare REST vs SOAP, then explore XML-RPC and JSON-RPC for simpler alternatives.