0
# WSSE Security
1

2
Web Services Security features including username tokens, digital signatures, and authentication mechanisms for secure SOAP communication. Zeep supports WS-Security standards for authentication and message integrity.
3

4
## Capabilities
5

6
### Username Token Authentication
7

8
WS-Security username token for basic authentication with optional password digest.
9

10
```python { .api }
11
class UsernameToken:
12
    def __init__(
13
        self,
14
        username: str,
15
        password: str = None,
16
        password_digest: str = None,
17
        use_digest: bool = False,
18
        nonce: str = None,
19
        created: str = None,
20
        timestamp_token=None,
21
        zulu_timestamp: bool = None,
22
        hash_password: bool = None
23
    ):
24
        """
25
        Create username token for WS-Security authentication.
26

27
        Parameters:
28
        - username: Username for authentication
29
        - password: Password for authentication (required unless password_digest provided)
30
        - password_digest: Pre-computed password digest
31
        - use_digest: Use password digest instead of plain text (deprecated, use password_digest param)
32
        - nonce: Custom nonce value (auto-generated if not provided)
33
        - created: Custom created timestamp (auto-generated if not provided)
34
        - timestamp_token: Custom timestamp token configuration
35
        - zulu_timestamp: Use 'Z' suffix in timestamps instead of +00:00
36
        - hash_password: Hash password before creating digest (for special services)
37
        """
38
```
39

40
### Digital Signatures
41

42
Digital signature support for message integrity and authentication using X.509 certificates.
43

44
```python { .api }
45
class Signature:
46
    def __init__(self, key_file: str, cert_file: str):
47
        """
48
        Create digital signature configuration.
49
        
50
        Parameters:
51
        - key_file: Path to private key file (PEM format)
52
        - cert_file: Path to certificate file (PEM format)
53
        """
54

55
class BinarySignature(Signature):
56
    """
57
    Binary security token signature using X.509 certificates.
58
    
59
    Supports embedding certificate directly in SOAP header.
60
    """
61

62
class MemorySignature(Signature):
63
    """
64
    In-memory signature configuration for certificates loaded from memory.
65
    
66
    Alternative to file-based signatures when certificates are in memory.
67
    """
68
```
69

70
### Security Composition
71

72
Combine multiple WS-Security elements in a single SOAP request.
73

74
```python { .api }  
75
class Compose:
76
    def __init__(self, *elements):
77
        """
78
        Compose multiple WS-Security elements.
79
        
80
        Parameters:
81
        - *elements: Security elements to combine (tokens, signatures, etc.)
82
        """
83
```
84

85
## Usage Examples
86

87
### Username Token Authentication
88

89
```python
90
from zeep import Client
91
from zeep.wsse import UsernameToken
92

93
# Plain text username token
94
wsse = UsernameToken('myusername', 'mypassword')
95
client = Client('http://example.com/secure-service.wsdl', wsse=wsse)
96

97
# Username token with password digest (more secure)
98
wsse_digest = UsernameToken('myusername', 'mypassword', use_digest=True)
99
client = Client('http://example.com/secure-service.wsdl', wsse=wsse_digest)
100

101
# Call secured operation
102
result = client.service.SecureOperation(param='value')
103
```
104

105
### Digital Signature Authentication
106

107
```python
108
from zeep import Client
109
from zeep.wsse import Signature
110

111
# Sign requests with X.509 certificate
112
wsse = Signature(
113
    key_file='/path/to/private-key.pem',
114
    cert_file='/path/to/certificate.pem'
115
)
116

117
client = Client('http://example.com/signed-service.wsdl', wsse=wsse)
118
result = client.service.SignedOperation(param='value')
119
```
120

121
### Binary Security Token
122

123
```python
124
from zeep import Client  
125
from zeep.wsse import BinarySignature
126

127
# Use binary security token with embedded certificate
128
wsse = BinarySignature(
129
    key_file='/path/to/private-key.pem',
130
    cert_file='/path/to/certificate.pem'
131
)
132

133
client = Client('http://example.com/service.wsdl', wsse=wsse)
134
result = client.service.SecureOperation(param='value')
135
```
136

137
### Multiple Security Elements
138

139
```python
140
from zeep import Client
141
from zeep.wsse import UsernameToken, Signature, Compose
142

143
# Combine username token and signature
144
username_token = UsernameToken('user', 'pass', use_digest=True)
145
signature = Signature('/path/to/key.pem', '/path/to/cert.pem')
146

147
# Compose multiple security elements
148
wsse = Compose(username_token, signature)
149

150
client = Client('http://example.com/multi-secure.wsdl', wsse=wsse)
151
result = client.service.MultiSecureOperation(param='value')
152
```
153

154
### Memory-based Certificates
155

156
```python
157
from zeep import Client
158
from zeep.wsse import MemorySignature
159

160
# Load certificates from memory (useful for deployment scenarios)
161
private_key_data = load_private_key_from_config()
162
certificate_data = load_certificate_from_config()
163

164
wsse = MemorySignature(private_key_data, certificate_data)
165
client = Client('http://example.com/service.wsdl', wsse=wsse)
166
```
167

168
### Security with Custom Settings
169

170
```python
171
from zeep import Client, Settings
172
from zeep.wsse import UsernameToken
173

174
# Combine security with strict XML settings
175
settings = Settings(
176
    strict=True,
177
    forbid_dtd=True,
178
    forbid_entities=True,
179
    force_https=True
180
)
181

182
wsse = UsernameToken('secure_user', 'strong_password', use_digest=True)
183

184
client = Client(
185
    'https://secure-service.com/service.wsdl',
186
    wsse=wsse,
187
    settings=settings
188
)
189

190
result = client.service.HighSecurityOperation(
191
    sensitive_data='confidential_value'
192
)
193
```
194

195
## Security Best Practices
196

197
### Password Digest Usage
198

199
Always use password digest for username tokens in production:
200

201
```python
202
# Good: Password digest enabled
203
wsse = UsernameToken('user', 'password', use_digest=True)
204

205
# Avoid: Plain text password (only for development)
206
wsse = UsernameToken('user', 'password', use_digest=False)
207
```
208

209
### Certificate Management
210

211
Store certificates securely and use appropriate file permissions:
212

213
```python
214
import os
215
from zeep.wsse import Signature
216

217
# Ensure private key has restricted permissions
218
key_file = '/secure/path/private-key.pem'
219
os.chmod(key_file, 0o600)  # Read only by owner
220

221
wsse = Signature(key_file, '/path/to/certificate.pem')
222
```
223

224
### HTTPS Enforcement
225

226
Always use HTTPS with security elements:
227

228
```python
229
from zeep import Client, Settings
230
from zeep.wsse import UsernameToken
231

232
settings = Settings(force_https=True)
233
wsse = UsernameToken('user', 'password', use_digest=True)
234

235
# This will enforce HTTPS for all connections
236
client = Client('https://service.com/secure.wsdl', wsse=wsse, settings=settings)
237
```