[security-services] Alternative "flattened" status code proposal

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

Here's an alternate approach to the nested design I proposed last month
that appears to be favored for SOAP at the moment. It's a sequential
"array" of status codes instead of a nested design. The "well-known"
code is the first one in the set, by position. Rather than providing
arbitrary levels of specificity, this proposal really only allows two
inherent levels, making it similar to the HTTP (and others) "error
range" design.

Either proposal can use elements or attributes for the actual codes. I
think my first proposal was attribute-centric. This one uses elements.

I think with either proposal, the first decision to make is the
top-level set of codes SAML needs to define, and then just decide on
which approach is preferred for the more specific codes.

The proposed schema, replacing the current string enumeration of
StatusCodeType:

<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="StatusDetailType">
    <sequence>
        <any namespace="##any" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
        <anyAttribute namespace="##any" processContents="lax"/>
    </sequence>
</complexType>
<complexType name="StatusCodeType">
    <sequence>
        <element name="Value" type="samlp:StatusCodeEnumType"/>
        <element name="Subcode" type="QName" minOccurs="0"
minOccurs="unbounded"/>
    </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="samlp:StatusDetailType"
minOccurs="0"/>
    </sequence>
</complexType>

In Response, replacing the StatusCode attribute, 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 Value element MUST contain a QName equal to one of the
StatusCodeEnumType values. It MAY contain additional Subcode elements
containing arbitrary Qnames. A receiver SHOULD provide as many Subcode
elements as needed 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 first Value 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.

-----------

If it helps, here are a couple of example Status structures based on
these proposals.

For the first, nested approach:

<Status>
  <Code Value="samlp:Sender">
    <Code Value="appns:AccessDenied"/>
  </Code>
</Status>

The same idea expressed with this proposal:

<Status>
  <Code>
    <Value>samlp:Sender</Value>
    <Subcode>appns:AccessDenied</Subcode>
  </Code>
</Status>

-- Scott