1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
1. Introduction.
SOAP (Simple Object Access Protocol) 1.1 is a standard proposed by Microsoft,
IBM, and other contributors for RPC-like interactions using XML. It defines a
mechanism for defining messages in XML, and for sending them over HTTP.
Since its introduction, it has had increased attention, and it is expected to
provide the foundation for many future Web-based services.
SOAP 1.1 has three main parts. One is a message format that uses an envelope
and body metaphor to wrap XML data for transmission between parties.
The second is a restricted definition of XML data for making strict RPC-like
calls through SOAP, without using a predefined XML schema. Finally, it
provides a binding for SOAP messages to HTTP and extended HTTP. [soap1.1]
This document describes how to use SOAP to send and receive SAML messages.
An additional section of the SAML specification ("SOAP Profile") defines how
to use SAML as an authentication mechanism for SOAP. In other words, this
section describes using SAML over SOAP, and that section describes using SAML
for SOAP.
Like SAML, SOAP can be used over multiple underlying transports. This
document describes protocol independent aspects of soap binding and calls
out the use of HTTP protocol and makes recomendations for http specifics,
including http headers, error reporting, authentication, message integrity,
and confidentiality.
2. Overview.
SOAP messages consist of three elements: an envelope, header data, and a
message body. SAML messages (queries and responses) are enclosed in the
SOAP message body.
SOAP 1.1 also defines an optional data encoding system. This system is not
used for the SOAP protocol binding for SAML. This means that SAML messages
can be transported using SOAP without re-encoding from "standard" SAML to a
SAML-like SOAP encoding.
The system model used for SAML conversations over SOAP is a simple
request-response model. A sending party sends a SAML query in the body of a
SOAP message. The receiving party processes the SAML query and returns a
SAML query response in the body of another SOAP message.
A brief glossary:
SAML conversation: an exchange of a SAML query and a SAML response.
sending party: The party sending a message.
receiving party: The party receiving a message.
1
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
querying party: The party sending a query message.
responding party: The party sending a response.
3. SOAP Binding.
3.1 Namespaces
All SAML messages encoded in SOAP MUST include XML namespace qualifiers,
as specified by the core assertions and messages definition.
[Rationale: Some SOAP message processors require a namespace. Also, the
namespace prevents conflicts with other standards and schemata.]
SOAP envelope namespace:
SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope [soap1.1]
3.2 SOAP Headers
The sending party in a SAML conversation over SOAP MAY add arbitrary headers
to the SOAP message.
[Rationale: some SOAP software and libraries may add headers to a SOAP
message that are out of the control of the SAML-aware process. Also, some
headers may be needed for underlying protocols that require routing of
messages.]
The receiving party MAY NOT require any headers for the SOAP message.
[Rationale: requiring extra headers will cause fragmenting of the standard
and will hurt interoperability.]
3.3 SAML Queries.
A SAML query is stored as the child of the <SOAP-ENV:body> element of a SOAP
message. The querying party MUST send one SAML query. The querying party
MUST NOT send more than one SAML query per SOAP message. The querying party
MUST NOT include any additional XML elements in the SOAP body.
On receiving a SAML query as a SOAP message, the receiving party MUST return
either a SAML query response or a SOAP fault code.
3.4 SAML Query Responses.
A SAML query response is stored as the child of the <SOAP-ENV:body> element
of a SOAP message. The message MUST contain exactly one SAML query response.
The querying party MUST NOT include any additional XML elements in the SOAP
body.
2
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
On receiving a SAML query response in a SOAP message, the querying party
MUST NOT send a fault code or other error messages to the sending party.
[Rationale: The format for the message interchange is a simple
request-response. Adding additional error conditions, notifications, etc.
would needlessly complicate the protocol.]
3.5 Fault Codes.
If a responding party cannot, for some reason, process a SAML query, it
should return a SOAP fault code. Fault codes MUST NOT be sent for errors
within the SAML problem domain, e.g. as a signal that the subject is not
authorized to access an object in an authorization query.
The four fault codes (VersionMismatch, MustUnderstand, Client, Server)
defined by SOAP 1.1 are sufficient to define any SOAP-related errors.
Responding parties MUST NOT use any additional fault codes, or sub-defined
fault codes, in a fault response.
Responding parties MAY provide additional fault information, such as
descriptions and details, as defined by SOAP.
[Rationale: some SOAP processors may add fault information automatically.]
3.6 Authentication.
Authentication of parties is REQUIRED. Authentication protocol is influenced
by the underlying transport. See section 4.2 for details on authentication
in HTTP environment.
3.7 Message Integrity.
Message integrity of both requests and responses is REQUIRED.
SAML requests and responses MAY be signed according to [saml-dsig]
specification.
Security layer in the underlying transport MAY be used to ensure message
integrity.
[Should we allow to sign soap message by including dsig:Signature
element in the header with mustUnderstand="1".
Soap profile allows inclusion of ds:KeyInfo into soap header to ensure
message integrity. Soap profile also mentions that this key could be
generated by the sender just for this purpose.]
3
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
3.8 Confidentiality.
Currently SOAP does not specify standard message-oriented technique for
confidentiality. This will only be possible when XML encryption standard
becomes available. So for the near future we have to depend on facilities
provided by the substrate protocol over which SOAP is layered.
Communicating parties MAY encrypt messages if confidentiality is required.
4. HTTP Specifics.
SOAP HTTP binding is mandatory to implement.
SOAP HTTP binding SHOULD work with HTTP/1.0 [rfc1945] and HTTP/1.1. [rfc2616]
SOAP HTTP binding MAY use HTTP extensions framework [rfc2774] provided both
parties understand extensions being used.
SOAP request is mapped into HTTP POST method [soap1.1].
HTTP media type should be set to text/xml [soap1.1]
SOAPAction header MUST be used to indicate the intent of SOAP HTTP request
[soap1.1] [Should we define standard value for SOAPAction header?]
4.1. HTTP Headers.
HTTP 1.1 should not include Cache-Control header field in the response to
POST request unless it's value is set to no-store. Expires response header
field should not be included, unless it is disabled by Cache-Control header
with the value of no-store.
[Rationale: HTTP proxies should not cache POST request responses carrying
SAML assertions]
There are no other restrictions on HTTP headers.
[What should be the value for the character set parameter of ContentType header?]
4.2 Authentication.
Following authentication protocols MUST be supported:
1. HTTP basic authentication [rfc2617].
2. HTTP digest authentication [rfc2617].
3. HTTPS server authentication with server-side certificate.
4. HTTPS client authentication with client-side certificate.
The use of server side certificate is mandatory in HTTPS deployment.
4
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
4.3 Message Integrity.
HTTPS MAY be used to ensure message integrity.
Private key infrastructure MAY be used to ensure message integrity. [please comment]
Content-MD5 entity header MAY be used in the absence of intermidearies for message
integrity. [please comment]
4.4 Message Confidentiality.
HTTPS MAY be used to ensure message confidentiality.
Private key infrastructure MAY be used to insure message confidentiality. [please
comment]
4.5 Security Considerations.
Each combination of authentication-message integrity-confidentiality should
be analyzed for vulnerability in the context of deployment environment.
(See security considerations document [saml-sec-cons] for detailed discussion).
[Rfc2617] provides description of possible attacks in HTTP environment
using basic and digest authentication schemes.
4.6 Error reporting.
If asserting party refuses to perform saml message exchange with the requestor
it should return "403 Forbidden" response. In this case content of the soap
body is undefined.
In case of a SOAP error while processing SOAP request the SOAP HTTP server
MUST use "500 Internal Server Error" response and include a SOAP message in
response containing a SOAP Fault element. [soap1.1]. This type of errors
should be returned for soap related errors detected before control is passed
to the soap processor, or when soap processor reports internal error.
Examples include situations when soap namespace is incorrect, saml schema can
not be located, soap message signature does not validate, saml processor runs
out of memory, etc.
In case of a SAML processing error the SOAP HTTP server MUST respond with
"200 OK" and include saml specified error description as a child of the
SOAP-ENV:Body element. For complete list of saml error codes see [...].
Referenced Documents
[soap1.1] Simple Object Access Protocol (SOAP) 1.1. W3C Note 08 May 2000.
http://www.w3.org/TR/2000/NOTE-SOAP-20000508
[rfc1945] Hypertext Transfer Protocol -- HTTP/1.0
http://www.ietf.org/rfc/rfc1945.txt
[rfc2616] Hypertext Transfer Protocol -- HTTP/1.1
http://www.ietf.org/rfc/rfc2616.txt
[rfc2617] HTTP Authentication: Basic and Digest Access Authentication.
http://www.ietf.org/rfc/rfc2617.txt
5
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
[rfc2774] An HTTP Extension Framework
http://www.ietf.org/rfc/rfc2774.txt
[saml-core] Security Assertions Markup Language. Core assertion Architecture
[saml-protocol] Security Assertions Markup Language. Protocols Schema.
[saml-dsig] SAML and XML Signature Syntax and Processing.
[saml-sec-cons] Security Assertions Markup Language. Security Considerations.
Examples.
Authentication assertion query and response.
POST /SamlService HTTP/1.1
Host: www.whatever.com
Content-Type: text/xml
Content-Length: nnn
SOAPAction: "SAML-URI"
<SOAP-ENV:Envelope xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<samlp:Request xmlns:samlp="..." xmlns:saml="..."
xmlns:ds="...">
<ds:Signature> ... </ds:Signature>
<samlp:AuthenticationQuery>
...
</samlp:AuthenticationQuery>
</samlp:Request>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: nnnn
<SOAP-ENV:Envelope xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<samlp:Response xmlns:samlp="..." xmlns:saml="..."
xmlns:ds="..." samlp:StatusCode="Success">
<ds:Signature> ... </ds:Signature>
<saml:AssertionSimple>
<saml:AuthenticationStatement>
...
</saml:AuthenticationStatement>
</saml:AssertionSimple>
</samlp:Response>
</SOAP-ENV:Body>
6
277
278
</SOAP-ENV:Envelope>
7