HTTP binding for SAML messages

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.

Leave a Reply

Your email address will not be published. Required fields are marked *