An HTTP Binding for SAML Messages ---------------------------------------------------------------------- Evan Prodromou, Outlook Technologies, Inc. 15 May 2001 1. Purpose ---------- This document describes an HTTP 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 --------------- HTTP is among the most commonly used Internet application protocol today. There are any number of implementations of the protocol that allow rapid development of dynamic servers or clients. With the possible exception of SMTP mail servers, HTTP servers withstand the the greatest collective load, in terms of performance, stability, and security, of any other class of software. For these reasons -- widespread use, robust implementations, and diverse development platforms -- it makes sense to leverage HTTP, and HTTP software, for the exchange of SAML messages. The following binding description derives from the HTTP binding provided with the AuthXML standard (see references). Note that the current version of SAML as of this writing has two different message formats, which will probably change over time. For this reason, this binding document merely refers to them as "request messages" and "response messages" without particular information about the content or structure of the message. Note that there is a separate binding for passing SAML assertions or assertion tokens from a standard Web browser to a Web server. This document does not treat that issue. Instead, it concentrates on using HTTP as a transport layer for SAML messages, without the restrictions that standard Web browsers impose. In most cases, this binding will be used as a service-to-service binding, rather than a user-to-service binding. Some design goals of this binding are as follows: * Enable using existing HTTP software (Web servers, client libraries) to create SAML services. * Minimize requirements for supporting the somewhat complex HTTP protocol. * Minimize the information carried in HTTP headers and other data. Except in extreme situations, information should be passed as SAML. Readers of this document should be familiar with HTTP/1.1, which is linked in the references section. 3. Overview ----------- The message protocol for SAML is based on a request-response metaphor. This naturally maps to the HTTP request-response method. So, for most types of interaction between systems, a request message is sent as an HTTP request, and a response message is sent as an HTTP response. In the discussion that follows, the following terms are used: * request message -or- request: A SAML request XML object. * response message -or- response: A SAML response XML object. * HTTP request: An HTTP request, as distinct from a SAML request. * HTTP response: An HTTP response, as distinct from a SAML response. * requester: The party sending the request. * responder: The party sending the response. 4. HTTP Binding --------------- 4.1. Connections As with all HTTP connections, the requester will initiate the connection. Connections MUST be one way. Multiple requests and corresponding responses MAY be sent over a single connection, per the HTTP 1.1 specification. The requester MUST only send requests through the connection, and the responder MUST only send responses through the connection. If the parties to the conversation exchange roles. [Rationale: most HTTP implementations have a clear delineation between HTTP client and HTTP server interfaces. Sending requests to a client implementation may cause unexpected behavior in the client.] The Connection header MAY be added to an HTTP request to request that the connection be closed after the response is given. "Connection: close" is the only allowed field in this header, in which case the responder MUST add the "Connection: close" header to the response and MUST close the connection after completing the response. If the "Connection: close" header is not added to the request, the connection will be handled per the default for the HTTP version of the request. If the HTTP version of the request is 1.0, the connection will be automatically closed by the responder. If the HTTP version is 1.1, the connection will be maintained by the responder, unless a "Connection: close" header was added to the response (See section 4.3 below). 4.2. Request Messages A request message is bound to an HTTP request. The request MUST use the POST method. The HTTP version MUST be one of "1.0" or "1.1". The request MUST have a Content-Type of "text/xml". The content of the HTTP request MUST be exactly one request message. Additional content MUST NOT be included in the HTTP request. The Host, Date, Content-Type and Content-Length headers MUST be provided in the HTTP request and be correct. A Connection header may be added as noted above in section 4.1. Additional HTTP headers MAY be provided, but parties in the conversation MUST ignore those other headers. [Rationale: many existing HTTP libraries will add additional headers to an HTTP request. The intent is to ensure a minimal number of headers required to handle the binding, without requiring that implementations write their own HTTP code.] Content-Encoding or Transfer-Encoding schemes MUST NOT be used. [Rationale: SAML messages are relatively small and should not require chunked encoding or compression. Forbidding Content- or Transfer-Encoding will allow implementers to safely ignore these fairly advanced and costly HTTP features.] 4.3. Response Messages If a request can be handled and generates a response, the response will be bound to an HTTP response message. If the responder cannot or will not generate a SAML response, the responder MUST send one of the HTTP error responses defined in section 4.6. The rest of this section will treat only successful responses. [Note that success, in this context, means that a SAML response was generated. It does not mean that the request was fulfilled or have domain level meaning, such as that authorization was granted, etc. The SAML response may have failure notifications per the SAML protocol.] The HTTP response MUST have a status code of 200. The HTTP version MUST be one of "1.0", "1.1". The response MUST have a Content-Type of "text/xml". The content of the HTTP response MUST be exactly one response message. Additional content MUST NOT be included in the HTTP response. The Host, Date, Content-Type and Content-Length headers MUST be provided in the HTTP response and be correct. A Connection header may be added as noted above in section 4.1. Additional HTTP headers MAY be provided, but parties in the conversation MUST ignore those other headers. Content-Encoding or Transfer-Encoding schemes MUST NOT be used. 4.4. Message Integrity The integrity of both requests and responses may be preserved in one of two ways. 4.4.1. XML Signature If this technique is used, an XML digital signature MUST be added to the entire request or response. The digital signature MAY be embedded in the message, or the message MAY be embedded in the signature. 4.4.2. HTTP/S with Certificates Alternately, the HTTP conversation may be conducted over an Secure Sockets Layer (SSL) connection. In this case, both parties (requester and responder) MUST provide digital certificates for the SSL layer. 4.5. Message Confidentiality HTTP/S MAY be used preserve message confidentiality. If integrity is protected using XML Signatures, neither party is required to provide a digital certificate. 4.6. Errors The following error messages may be sent by the responder for a SAML message. [Note that in the following section, the error text is not normative, but gives an indication of what the error code means. Only the error number is normative.] For all status values besides "200", the "Connection: close" header MUST be sent, and the connection between requester and responder MUST be closed. 4.6.1. 200 OK The responder received the request and successfully generated a response. The response may contain a SAML error code or further SAML information. The meaning of the 200 message is "more info in SAML content." 4.6.2. 400 Bad Request The responder received the request, but the request was ill-formed in some way. The content of the Response is undefined, but it SHOULD NOT be a SAML message. The content of the Response MAY be a stock piece of HTML or plain text explaining the nature of the error. [Rationale: Some HTTP server software will add stock explanations for error status codes.] This result code is appropriate for requests with bad HTTP headers, HTTP methods other than "POST", or with syntactically incorrect SAML content. 4.6.3. 403 Forbidden The responder has received the request, but refuses to perform a SAML message exchange with the requestor. The content of the Response is undefined, but it SHOULD NOT be a SAML message. The content of the Response MAY be a stock piece of HTML or plain text explaining the nature of the request. 4.6.4. 500 Internal Server Error The responder has received the request but has failed to produce a response, due to internal error. The content of the Response is undefined, but it SHOULD NOT be a SAML message. The content of the Response MAY be a stock piece of HTML or plain text explaining the nature of the request. References ---------- "AuthXML: A Specification for Authentication Information In XML", version 0.3, Prodromou et. al., 14 Dec 2001. "RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1", http://www.w3.org/Protocols/rfc2616/rfc2616.html, W3C, Jun 1999.