A SOAP 1.1 Protocol Binding for SAML Messages ---------------------------------------------------------------------- draft-prodromou-soap-binding-00.txt 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 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 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.