SOAP Header Elements — WS-Addressing, WS-Security, and Custom Metadata

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

The SOAP Header is an optional child of the Envelope that carries metadata about the message, including routing information, security credentials, transaction contexts, and custom application data.

What You'll Learn

• The purpose of the SOAP Header
• Common header elements (WS-Addressing, WS-Security)
• How to add custom headers

Why It Matters

Headers enable SOAP to support enterprise features like end-to-end security, message routing through intermediaries, and transaction coordination—all without modifying the Body content.

<soap:Header>
  <!-- WS-Addressing headers -->
  <wsse:Security>
    <wsse:UsernameToken>
      <wsse:Username>api-user</wsse:Username>
      <wsse:Password>api-password</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

WS-Addressing Headers

def create_wsa_headers(action, message_id, reply_to, to):
    """Create WS-Addressing header elements"""
    return f'''
<wsa:MessageID>{message_id}</wsa:MessageID>
<wsa:Action>{action}</wsa:Action>
<wsa:ReplyTo>
  <wsa:Address>{reply_to}</wsa:Address>
</wsa:ReplyTo>
<wsa:To>{to}</wsa:To>
'''.strip()

# Usage
wsa_headers = create_wsa_headers(
    action='http://dodatech.com/SubmitThreat',
    message_id='uuid:12345678-1234-5678-1234-567812345678',
    reply_to='http://www.w3.org/2005/08/addressing/anonymous',
    to='https://api.dodatech.com/soap/threat-intel'
)

WS-Security Headers

import hashlib
import base64
from datetime import datetime

def create_wsse_header(username, password):
    """Create WS-Security UsernameToken header"""
    created = datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ')
    nonce = base64.b64encode(hashlib.sha256(str(datetime.utcnow().timestamp()).encode()).digest()).decode()

    password_digest = base64.b64encode(
        hashlib.sha256(
            (nonce + created + password).encode()
        ).digest()
    ).decode()

    return f'''
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <wsse:UsernameToken>
    <wsse:Username>{username}</wsse:Username>
    <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">
      {password_digest}
    </wsse:Password>
    <wsse:Nonce>{nonce}</wsse:Nonce>
    <wsu:Created>{created}</wsu:Created>
  </wsse:UsernameToken>
</wsse:Security>
'''.strip()

Custom Application Headers

def add_custom_header(api_version, request_id, client_name, locale='en-US'):
    """Add custom application context headers"""
    return f'''
<ns:ApplicationContext>
  <ns:ApiVersion>{api_version}</ns:ApiVersion>
  <ns:RequestId>{request_id}</ns:RequestId>
  <ns:ClientName>{client_name}</ns:ClientName>
  <ns:Locale>{locale}</ns:Locale>
  <ns:Timestamp>{datetime.utcnow().isoformat()}Z</ns:Timestamp>
</ns:ApplicationContext>
'''.strip()

Common Mistakes

1. Not Using the mustUnderstand Attribute

Critical headers (like security) should use soap:mustUnderstand="1" to force intermediaries to Process them.

2. Including Sensitive Data Without Encryption

Headers are visible in the SOAP message. Encrypt sensitive header content using WS-Security.

3. Omitting Required WS-Addressing Headers

SOAP intermediaries may require wsa:To and wsa:Action headers for routing. Missing them causes routing failures.

4. Incorrect Namespace Declarations

Header namespaces must be declared in the Envelope or Header. Undeclared namespaces cause Parsing errors.

5. Not Handling Multiple Headers

A message can have multiple headers from different namespaces. Ensure your parser handles all of them.

Practice Questions

1. What is the purpose of the SOAP Header?
2. What does WS-Addressing provide?
3. What is WS-Security used for?
4. What does mustUnderstand="1" do?
5. Can headers be mandatory?

Answers

1. To carry metadata about the SOAP message. 2. Transport-neutral addressing for routing through intermediaries. 3. Authentication, message integrity, and confidentiality. 4. It signals that the header must be processed by the recipient. 5. Yes, using the mustUnderstand attribute.

Challenge

Build a SOAP header Builder that supports WS-Addressing, WS-Security (UsernameToken with password digest), custom application context headers, properly handles mustUnderstand, and validates namespace declarations.

FAQ

Mini Project

Build a SOAP header injection middleware that: adds WS-Security UsernameToken to outgoing requests, adds WS-Addressing headers for routing, supports custom application context, validates incoming headers, and logs header processing results.

What's Next

• Learn about SOAP Body for request and response structure
• Explore SOAP Fault details for error handling
• Continue to WSDL structure for service description