OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

security-editors message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Draft Submission


Draft submission for HTTP binding for SAML messages.

~ESP

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.

-- 
Evan Prodromou <evan@outlook.net>
Applications Lead
Outlook Technologies, Inc.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC