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

["Hallam-Baker, Phillip" <pbaker@verisign.com>]

I have had to re-edit the schema somewhat to conform to the coding style
previously agreed.

Is the recursive inclusion in Substatus code type intentional?? I have
assumed not since if it were intentional I would have expected notice to be
drawn to it.

<complexType name="SubStatusCodeType">
    <sequence>
        <element name="Value" type="QName"/>
        <element name="Code" type="samlp:SubStatusCodeType"
minOccurs="0"/>
    </sequence>
</complexType>


These changes result in the following schema:

	<element name="Response" type="samlp:ResponseType"/>
	<complexType name="ResponseType">
		<complexContent>
			<extension base="samlp:ResponseAbstractType">
				<sequence>
					<element ref="samlp:Status"/>
					<element ref="saml:Assertion"
minOccurs="0" maxOccurs="unbounded"/>
				</sequence>
			</extension>
		</complexContent>
	</complexType>
	<element name="Status" type="samlp:StatusType"/>
	<complexType name="StatusType">
		<sequence>
			<element ref="samlp:StatusCode"/>
			<element name="Message" type="string" minOccurs="0"
maxOccurs="unbounded"/>
			<element ref="samlp:Detail" minOccurs="0"/>
		</sequence>
	</complexType>
	<element name="StatusCode" type="samlp:StatusCodeType"/>
	<complexType name="StatusCodeType">
		<sequence>
			<element ref="samlp:SubStatusCode" minOccurs="0"/>
		</sequence>
		<attribute name="Value" type="samlp:StatusCodeEnumType"/>
	</complexType>
	<simpleType name="StatusCodeEnumType">
		<restriction base="QName">
			<enumeration value="samlp:Success"/>
			<enumeration value="samlp:VersionMismatch"/>
			<enumeration value="samlp:Receiver"/>
			<enumeration value="samlp:Sender"/>
		</restriction>
	</simpleType>
	<element name="SubStatusCode" type="samlp:SubStatusCodeType"
minOccurs="0"/>
	<complexType name="SubStatusCodeType">
		<attribute name="Value" type="QName"/>
	</complexType>
	<element name="Detail" type="samlp:DetailType"/>
	<complexType name="DetailType">
		<sequence>
			<any namespace="##any" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
		</sequence>
	</complexType>

Phillip Hallam-Baker FBCS C.Eng.
Principal Scientist
VeriSign Inc.
pbaker@verisign.com
781 245 6996 x227


> -----Original Message-----
> From: Scott Cantor [mailto:cantor.2@osu.edu]
> Sent: Wednesday, January 09, 2002 12:36 AM
> To: SAML
> Subject: [security-services] A "final" proposal on status codes
> 
> 
> 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
> 
> 
> ----------------------------------------------------------------
> To subscribe or unsubscribe from this elist use the subscription
> manager: <http://lists.oasis-open.org/ob/adm.pl>
>

Phillip Hallam-Baker (E-mail).vcf