SOAP 1.1 Protocol Binding

[Evan Prodromou <eprodromou@securant.com>]

Attached is a first draft of the SOAP 1.1 protocol binding. It's
fairly detailed, but the essential message of the protocol binding
("put queries and responses in message bodies") is extremely simple.

Thanks for your patience on this.

~ESP

A SOAP 1.1 Protocol Binding for SAML Messages
----------------------------------------------------------------------
Evan Prodromou, Securant Technologies, Inc.
12 Jun 2001

1. Purpose
----------

This document describes a SOAP 1.1 protocol binding for SAML
messages. It is intended as a submission for consideration by the
OASIS Security Services Technical Committee Bindings Group for
inclusion in the bindings section of the Security Assertions Markup
Language (SAML) 1.0 specification.

2. 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 through 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 

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 does not address the use of underlying transports directly,
although it makes recommendations for some transports in addressing
message integrity and confidentiality concerns.

Note that this protocol binding is relatively short. This is because
SOAP is a relatively simple protocol, and because most of the
difficult details of connections, routing, etc. are defined in the
SOAP 1.1 standard.

3. 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.
  querying party: The party sending a query message.
  responding party: The party sending a response.

4. SOAP Binding
---------------

4.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.]

4.2. 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.]

4.3. SAML Queries

A SAML query is stored as the child of the <SOAP: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 (section 4.3) or a SOAP fault code
(section 4.4).

4.4. SAML Query Responses

A SAML query response is stored as the child of the <SOAP: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.

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.]

4.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.]

4.6. Integrity

4.6.1. XML Digital Signature

To ensure message integrity, the parties in a SAML conversation MAY
add a XML Digital Signature to the SAML query. The parties MUST NOT
add signatures in either the headers or the envelope of the SOAP
message.

4.6.2. HTTP/S with Certificates

Alternately, the parties MAY use the underlying transport of the SOAP
conversation to ensure message integrity. For SOAP messages sent over
HTTP, this would be HTTP/S with client certificates.

4.7. Confidentiality

To achieve message confidentiality, the parties in a SAML conversation
MAY use the confidentiality protection mechanism in the underlying
SOAP transport. For SOAP messages used over HTTP, this would be
HTTP/S.

References
----------

"Simple Object Access Protocol (SOAP) 1.1",
  http://www.w3.org/TR/SOAP/, W3C Note, 8 May 2000.


-- 
Evan Prodromou, Senior Architect        eprodromou@securant.com
Securant Technologies, Inc.             415-856-9551