[security-services] A "final" proposal on status codes

[Scott Cantor <cantor.2@osu.edu>]

This is largely a repost of my first proposal, with the schema adjusted
to align with SOAP. XMLP has apparently tenatively approved this for
SOAP, based on what I read.

------------------------

SAML needs an extensible, more flexible status code mechanism. This
proposal is a hierarchical Status structure to be placed inside Response
as a  required element. The Status element contains a nested Code tree
in which the top level Value attribute is from a small defined set that
SAML implementations must be able to create/interpret, while allowing
arbitrary detail to be nested inside, for applications prepared to
interpret further.

I mirrored some of SOAP's top level fault codes, while keeping SAML's
Success code, which doesn't exist in SOAP, since faults mean errors, not
status. I also eliminated the Error vs Failure distinction, which seems
to be intended to "kind of" mean Receiver/Sender, which is better made
explicit. Unknown didn't make sense to me either. Please provide
clarifications if these original codes should be kept.

The proposed schema is as follows, replacing the current string
enumeration of StatusCodeType with the new complex StatusType:

<simpleType name="StatusCodeEnumType">
    <restriction base="QName">
        <enumeration value="samlp:Success"/>
        <enumeration value="samlp:VersionMismatch"/>
        <enumeration value="samlp:Receiver"/>
        <enumeration value="samlp:Sender"/>
    </restriction>
</simpleType>
<complexType name="StatusCodeType">
    <sequence>
        <element name="Value" type="sampl:StatusCodeEnumType"/>
        <element name="Code" type="samlp:SubStatusCodeType"
minOccurs="0"/>
    </sequence>
</complexType>
<complexType name="SubStatusCodeType">
    <sequence>
        <element name="Value" type="QName"/>
        <element name="Code" type="samlp:SubStatusCodeType"
minOccurs="0"/>
    </sequence>
</complexType>
<complexType name="StatusType">
    <sequence>
        <element name="Code" type="samlp:StatusCodeType"/>
        <element name="Message" type="string" minOccurs="0"
maxOccurs="unbounded"/>
        <element name="Detail" type="anyType" minOccurs="0"/>
    </sequence>
</complexType>

In Response, delete the StatusCode attribute, and add:

<element name="Status" type="samlp:StatusType"/>

Some draft text for a new section, perhaps under 2.6.2 Response,
describing the structure might be:

SAML responses MUST include a Status element describing the outcome of
the requested operation in as much detail as the receiver desires to
express.

2.6.2.1 Element Status

The Status element contains a top-level status code, and optional
message and detail information.

<Code> [Required]
The top-level Code element MUST contain a Value element equal to one of
the StatusCodeEnumType values. It MAY contain additional nested Code
elements containing Value elements equal to arbitrary QNames. A receiver
SHOULD provide nested Code elements to fully describe error conditions
when possible, but a sender MUST be able to correctly process the
Response in a reasonable fashion by examining only the top-level Code
element. Four top-level values are defined:

Success - The request succeeded.

VersionMismatch - The receiver could not process the request because the
version was incorrect.

Receiver - The request could not be performed due to an error at the
receiving end.

Sender - The request could not be performed due to an error in the
sender or in the request.

<Message> [Optional]
Any number of Message elements may be included to describe the success
or failure condition in human-readable fashion. Multiple languages may
be included for I18N purposes.

<Detail> [Optional]
Arbitrary well-formed XML content may be included to pass application or
implementation-specific information to the sender. A receiver MUST NOT
require the sender understand the contents of Detail in order to process
the response in a reasonable fashion.

The Detail element can be interpreted by agreement between sender and
receiver and/or with use of the xsi:type attribute to describe the
schematic type of the content.

----------------------

An example of this proposal, say for the Incomplete response code Eve
proposed would look like:

<samlp:Response>
  ....
  <samlp:Status>
    <samlp:Value>samlp:Receiver</samlp:Value>
    <samlp:Code>
      <samlp:Value>samlp:Incomplete</samlp:Value>
    </samlp:Code>
    <samlp:Message>Not all the attributes could be
obtained.</samlp:Message>
  </samlp:Status>
</samlp:Response>

The processing model (in XPath terms) specifies to examine Status/Value
and optionally examine Status/Code/Value, Status/Code/Code/Value, etc.
as desired. Only the first step is strictly required.

-- Scott