|
||
Enlace Web Services Addressing 1.0 - SOAP Este documento es una traducción de la Recomendación del W3C sobre Enlace Web Services Addressing 1.0 - SOAP La versión inglesa de esta especificación es la única con valor normativo y puede encontrarse en: http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509" |
Por favor, consulte la sección de erratas de este documento, que puede incluir algunas correcciones normativas.
Este documento también está disponible en los siguientes formatos, que no son normativos: PDF, PostScript, XML y texto sin formato.
Vea también las traducciones.
Copyright © 2006 W3C® (MIT, ERCIM, Keio), todos los derechos reservados. Se aplican las reglas de responsabilidad, marca registrada y utilización de documentos del W3C.
La especificación Web Services Addressing proporciona mecanismos independientes del transporte para direccionar servicios web y mensajes. La especificación del enlace Web Services Addressing 1.0 - SOAP (este documento) define el enlace entre las propiedades abstractas definidas en Web Services Addressing 1.0 - Core y los mensajes SOAP.
Esta sección describe el estado del presente documento al momento de su publicación. El presente documento puede ser reemplazado por otros. Para ver una lista de las publicaciones actuales del W3C y la última revisión del presente informe técnico consulte el Índice de informes técnicos del W3C en http://www.w3.org/TR/.
Este documento es una Recomendación para la especificación del enlace de Web Services Addressing 1.0 con SOAP. Ha sido producido por el Grupo de trabajo para el direccionamiento de servicios web (WG), como parte de la Actividad en servicios web del W3C.
Ha sido revisado por miembros del W3C, por desarrolladores de software y por otros grupos del W3C y otras partes interesadas, y ha sido avalado como Recomendación del W3C por el Director. Es un documento estable y se lo puede emplear como material de referencia o citar en otro documento. El papel que desempeña el W3C en la creación de la Recomendación es atraer la atención hacia la especificación y fomentar su implementación masiva. Esto mejora la funcionalidad y la interoperabilidad de la Web.
El Grupo de trabajo ha realizado las siguientes correcciones a la Propuesta de recomendación, en respuesta a los comentarios recibidos: ahora se distinguen más claramente las referencias normativas de las informativas, y se han corregido algunos errores tipográficos. Existe un informe de implementación, que muestra que se han cumplido y superado los criterios de salida para la recomendación candidata; además existe un paquete de evaluación. Hay disponible una versión de este documento con marcas de cambio en relación con la versión anterior.
Si encuentra errores en este documento, por favor inclúyalos en la lista de correo public-ws-addressing-comments@w3.org ( archivo público).
Este documento se ha redactado conforme a la Política de patentes del W3C del 5 de febrero de 2004. W3C mantiene una lista pública de publicaciones de patentes pertinentes a los resultados del trabajo del grupo; en la página también se incluyen instrucciones para la publicación de patentes. Toda persona que tenga conocimiento fehaciente de una patente que, en su opinión, contenga Reivindicaciones Esenciales respecto de la presente especificación, deberá revelar dicha información según lo establece la sección 6 de la Política de Patentes del W3C.
1. Introducción
1.1 Convenciones de notación
1.2 Espacios de nombres
2. Característica SOAP 1.2
Addressing 1.0
2.1 Nombre de la característica
2.2 Descripción
2.3 Propiedades
2.4 Interacción con otras características de
SOAP
3. Módulo SOAP 1.2 Addressing
1.0
3.1 Nombre de módulo
3.2 Descripción
3.2.1 Envío de mensajes
3.2.2 Recepción de mensajes
3.3 Items adicionales del conjunto de
información
3.4 Enlace de propiedades de direccionamiento de
mensajes
3.5 Relación entre las cabeceras SOAP y las
propiedades de nivel de transporte
4. Extensión SOAP 1.1 Addressing
1.0
4.1 Nombre de extensión
4.2 Descripción
5. Direcciones en
SOAP
5.1 Uso de direcciones anónimas en extremos de respuesta
SOAP
5.1.1 SOAP 1.1/HTTP
5.1.2 SOAP 1.2
5.2 Uso de direcciones no anónimas en extremos de
respuesta SOAP
5.2.1 SOAP 1.1/HTTP
5.2.2 SOAP 1.2
6. Errores
6.1 Enlace de errores SOAP 1.2
6.2 Enlace de errores SOAP 1.1
6.3 Elementos de detalle de error
6.3.1 Problem Header QName
6.3.2 Problem IRI
6.3.3 Problem Action
6.3.4 Retry After
6.4 Errores predefinidos
6.4.1 Cabecera de direccionamiento
inválida
6.4.1.1
wsa:InvalidAddress
6.4.1.2
wsa:InvalidEPR
6.4.1.3
wsa:InvalidCardinality
6.4.1.4
wsa:MissingAddressInEPR
6.4.1.5
wsa:DuplicateMessageID
6.4.1.6
wsa:ActionMismatch
6.4.1.7
wsa:OnlyAnonymousAddressSupported
6.4.1.8
wsa:OnlyNonAnonymousAddressSupported
6.4.2 Message Addressing Header
Required
6.4.3 Destination
Unreachable
6.4.4 Action Not Supported
6.4.5 Endpoint Unavailable
7. Consideraciones
relativas a la seguridad
7.1 Determinación de confianza en referencias de
extremo
7.2 Otras consideraciones relativas a la
seguridad
7.3 Otras consideraciones relativas a los intermediarios
SOAP
8. Conformidad
9. Referencias
9.1 Referencias normativas
9.2 Otras referencias
A. Agradecimientos (no normativo)
Web Services Addressing 1.0 - Core [WS-Addressing Core] define un conjunto de propiedades abstractas (y su representación en la forma de conjunto de información XML [Conjunto de información XML]) para hacer referencia a extremos de servicios web y facilitar el direccionamiento de dichos extremos, de un extremo al otro, dentro de los mensajes. La especificación del enlace Web Services Addressing 1.0 - SOAP (este documento) define el enlace entre las propiedades abstractas definidas en Web Services Addressing 1.0 - Core y los mensajes SOAP.
El ejemplo siguiente muestra el empleo de estos mecanismos en un mensaje SOAP 1.2 que se envía desde http://example.com/business/client1 hasta http://example.com/fabrikam/Purchasing:
Ejemplo 1.1. Uso de propiedades de direccionamiento de mensajes en un mensaje SOAP 1.2.
(01) <S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing"> (02) <S:Header> (03) <wsa:MessageID>http://example.com/6B29FC40-CA47-1067-B31D-00DD010662DA</wsa:MessageID> (04) <wsa:ReplyTo> (05) <wsa:Address>http://example.com/business/client1</wsa:Address> (06) </wsa:ReplyTo> (07) <wsa:To>http://example.com/fabrikam/Purchasing</wsa:To> (08) <wsa:Action>http://example.com/fabrikam/SubmitPO</wsa:Action> (09) </S:Header> (10) <S:Body> (11) ... (12) </S:Body> (13) </S:Envelope>
Las líneas (02) a (09) representan la cabecera del mensaje SOAP, donde se utilizan los mecanismos definidos en la especificación. El cuerpo está representado por las líneas (10) a (12).
Las líneas (03) a (08) contienen las propiedades de direccionamiento de mensaje serializadas como bloques de cabecera SOAP. En concreto, la línea (03) especifica el identificador del mensaje y las líneas (04) a (06) especifican, en la forma de una referencia de extremo, el extremo al cual se deberían enviar las respuestas a este mensaje. La línea (07) especifica la dirección URI del receptor final del mensaje. La línea (08) especifica un URI de acción que identifica la semántica esperada.
Las palabras clave "DEBE" ("MUST"), "NO DEBE" ("MUST NOT"), "OBLIGATORIO" ("REQUIRED"), "DEBERÁ" ("SHALL"), "NO DEBERÁ" ("SHALL NOT"), "DEBERÍA" ("SHOULD"), "NO DEBERÍA" ("SHOULD NOT"), "RECOMENDADO" ("RECOMMENDED"), "PUEDE" ("MAY") y "OPCIONAL" ("OPTIONAL") en esta especificación deben interpretarse según se describe en RFC 2119 [IETF RFC 2119].
Para describir modelos de datos abstractos, esta especificación emplea la convención de notación definida por el conjunto de información XML [Conjunto de información XML]. En concreto, los nombres de propiedades abstractas aparecerán siempre entre corchetes (por ej., [una propiedad]).
Para la descripción de esquemas XML concretos [Estructuras de esquemas XML, Tipos de datos de esquemas XML], esta especificación emplea la convención de notación de WS-Security [WS-Security]. En concreto, cada miembro de la propiedad [children] (hijos) o [attributes] (atributos) de un elemento se describe con una notación de tipo XPath (por ej., /x:LaCabecera/x:UnaPropiedad/@valor1). El uso de {any} (cualquiera) indica la presencia de un comodín de elemento (<xs:any/>). El uso de @{any} indica la presencia de un comodín de atributo (<xs:anyAttribute/>).
A lo largo de esta especificación se emplean diversos prefijos de espacio de nombres, que se indican en el Cuadro 1.1. Obsérvese que la elección de un prefijo de espacio de nombres cualquiera es arbitraria y no es significativa desde un punto de vista semántico (véase [Espacios de nombres XML]).
Prefijo | Espacio de nombres |
---|---|
S | http://www.w3.org/2003/05/soap-envelope |
S11 | http://schemas.xmlsoap.org/soap/envelope |
wsa | http://www.w3.org/2005/08/addressing |
wsaw | http://www.w3.org/2006/02/addressing/wsdl |
xs | http://www.w3.org/2001/XMLSchema |
WS-Addressing se define en relación con el conjunto de información XML [Conjunto de información XML]. WS-Addressing es conforme al modelo de procesamiento de SOAP 1.2 [Infraestructura de mensajería SOAP 1.2] y también es compatible con SOAP 1.1 [SOAP 1.1] a los efectos de la compatibilidad hacia atrás. WS-Addressing se puede usar con servicios descritos mediante WSDL [WSDL 2.0 Core Language], según se describe en el enlace de Web Services Addressing 1.0 con WSDL [Enlace WS-Addressing WSDL]. Los ejemplos que se incluyen en esta especificación emplean una representación XML 1.0 [XML 1.0], pero esto no es obligatorio.
Todos los ítems de información definidos por esta especificación están identificados por el URI de espacio de nombres XML [Espacios de nombres XML] http://www.w3.org/2005/08/addressing. Resolviendo la referencia del URI de espacio de nombres XML se puede obtener un documento normativo para el esquema XML [Estructuras de esquemas XML , Tipos de datos de esquemas XML].
Esta sección define la característica SOAP 1.2 Addressing 1.0.
La característica SOAP 1.2 Addressing 1.0 se nombra con el siguiente URI:
http://www.w3.org/2005/08/addressing/feature
La característica SOAP 1.2 Addressing 1.0 ofrece una expresión dentro de SOAP de las propiedades abstractas de direccionamiento de mensaje definidas por la especificación Web Services Addressing 1.0 - Core [WS-Addressing Core].
Esta característica puede emplearse con cualquier pauta de intercambio de mensajes SOAP. Un enlace que admita esta característica DEBE ofrecer un medio de transmitir con los mensajes las propiedades que se enumeran más adelante y de reconstituir sus valores al recibir un mensaje.
La característica SOAP 1.2 Addressing 1.0 define las siguientes propiedades:
Corresponde a la propiedad abstracta [destination] (destino).
Corresponde a la propiedad abstracta [source endpoint] (extremo de origen).
Corresponde a la propiedad abstracta [reply endpoint] (extremo de respuesta).
Corresponde a la propiedad abstracta [fault endpoint] (extremo de error).
Corresponde a la propiedad abstracta [action] (acción).
Corresponde a la propiedad abstracta [message id] (identificador de mensaje).
Corresponde a la propiedad abstracta [relationship] (relación).
Corresponde a la propiedad abstracta [reference parameters] (parámetros de referencia).
Si la propiedad http://www.w3.org/2003/05/soap/features/action/Action de la característica Action de SOAP [SOAP 1.2: Adjuntos] tiene valor, entonces el valor de la propiedad http://www.w3.org/2005/08/addressing/feature/Action de la característica SOAP 1.2 Addressing 1.0 DEBE ser idéntico a aquél. Si los valores no coinciden, se produce un error de cabecera de direccionamiento inválida (ver 6.4.1 Cabecera de direccionamiento inválida).
El módulo SOAP 1.2 Addressing 1.0 define un conjunto de bloques de cabecera SOAP que brindan compatibilidad con la característica SOAP 1.2 Addressing 1.0 descrita en Característica SOAP 1.2 Addressing 1.0.
El módulo SOAP 1.2 Addressing 1.0 se identifica con el siguiente URI:
http://www.w3.org/2005/08/addressing/module
La característica SOAP 1.2 Addressing 1.0 (ver 2. Característica SOAP 1.2 Addressing 1.0) define un conjunto de propiedades SOAP y su correspondencia con las propiedades abstractas de direccionamiento de mensaje definidas por la especificación Web Services Addressing 1.0 - Core [WS-Addressing Core]. El módulo SOAP 1.2 Addressing 1.0 define cabeceras SOAP que se corresponden con la representación como conjunto de información XML de las propiedades abstractas de direccionamiento de mensajes definidas en Web Services Addressing 1.0 - Core.
Cuando se envía un mensaje, cada propiedad se representa mediante el ítem de información de elemento que corresponda, en la forma de un bloque de cabecera SOAP. De forma predeterminada, los bloques de cabecera resultantes apuntan al receptor último en la ruta del mensaje SOAP (obsérvese que se podrían escribir extensiones de WS-Addressing que especifiquen un direccionamiento diferente). En 3.4 Enlace de propiedades de direccionamiento de mensajes se describe el procesamiento adicional necesario para enlazar las propiedades de direccionamiento de mensajes con los bloques de cabecera SOAP.
En la recepción de un mensaje, los valores de las propiedades abstractas se obtienen a partir de los items de información de elemento correspondientes contenidos en el mensaje. Un mensaje NO DEBE contener más de una cabecera wsa:To, wsa:ReplyTo, wsa:FaultTo, wsa:Action o wsa:MessageID en dirección a un receptor; si el receptor encuentra cabeceras cuya cardinalidad es incorrecta, NO DEBE usarlas para definir los valores de las propiedades abstractas correspondientes. El receptor DEBE generar un error wsa:InvalidAddressingHeader (ver 6.4.1 Cabecera de direccionamiento inválida) si recibe un mensaje de esas características.
Observación:
El modelo de procesamiento de SOAP determina que las propiedades de direccionamiento de mensajes dirigidas a un intermediario normalmente no se retransmitan como propiedades de direccionamiento de mensaje cuando el mensaje se retransmite a lo largo de su ruta. Este comportamiento predeterminado puede anularse mediante la especificación del uso de una cabecera SOAP como parámetro de referencia o mediante el uso del atributo soap:relay.
El módulo SOAP 1.2 Addressing 1.0 define los siguientes items del conjunto de información XML:
Este atributo OBLIGATORIO (de tipo xs:boolean) indica si la cabecera de direccionamiento de mensaje es un parámetro de referencia; en la sección 3.4 Enlace de propiedades de direccionamiento de mensajes se brindan más detalles en relación con su empleo.
Cuando se direcciona un mensaje a un extremo, la representación como conjunto de información XML de cada propiedad de direccionamiento de mensaje que tenga un valor asignado se incorpora al mensaje en la forma de un bloque de cabecera SOAP, con estas restricciones adicionales:
Si la propiedad [reference parameters] tiene algún valor, éste se añade a la cabecera de mensaje SOAP. El ítem de información de elemento incluido en cada uno de los [reference parameters] (parámetros de referencia) (incluidos todos los elementos en [children], [attributes] e [in-scope namespaces]) se añade como bloque de cabecera SOAP al nuevo mensaje.
Observación:
La inserción de cabeceras SOAP en un mensaje implica una semántica particular. Puesto que el mecanismo de parámetros de referencia no impone restricciones al contenido de las cabeceras generadas, los proveedores de referencias de extremo deberían tomar los recaudos necesarios para asegurar que sus parámetros de referencia no den lugar a una semántica imprevista o errónea en el mensaje SOAP resultante. Por ejemplo, no sería recomendable usar un parámetro de referencia para enviar una cabecera WS-Security [WS-Security], puesto que usualmente dicha cabecera estará bajo el control de otras partes de la infraestructura SOAP y no puede haber más de una de esas cabeceras por mensaje.
Cada bloque de cabecera añadido como resultado de la regla anterior se anota con un atributo wsa:IsReferenceParameter (ver 3.3 Items adicionales del conjunto de información) cuyo valor sea una representación xs:boolean válida para "verdadero". Si el bloque de cabecera ya contiene un atributo wsa:IsReferenceParameter, se sustituye el atributo anterior.
Observación:
La validación de integridad de la propiedad [reference parameters] debe tener en cuenta el agregado de los atributos wsa:IsReferenceParameter y la correspondiente introducción del espacio de nombres WS-Addressing a la propiedad [in-scope namespaces].
El valor de cada propiedad de direccionamiento de mensaje que sea de tipo IRI DEBE serializarse en la forma de IRI absoluto en el bloque de cabecera SOAP correspondiente. No se aplicarán otros mecanismos de escape con signos %.
Se PUEDE omitir cada uno de los elementos o atributos opcionales cuyo valor coincida con el valor que tienen definido por defecto.
El ejemplo siguiente muestra el empleo del módulo SOAP 1.2 Addressing 1.0 para construir un mensaje dirigido a un extremo:
Ejemplo 3.1. Ejemplo de referencia de extremo.
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsaw="http://www.w3.org/2006/02/addressing/wsdl" xmlns:fabrikam="http://example.com/fabrikam" xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance" wsdli:wsdlLocation="http://example.com/fabrikam http://example.com/fabrikam/fabrikam.wsdl"> <wsa:Address>http://example.com/fabrikam/acct</wsa:Address> <wsa:Metadata> <wsaw:InterfaceName>fabrikam:Inventory</wsaw:InterfaceName> </wsa:Metadata> <wsa:ReferenceParameters> <fabrikam:CustomerKey>123456789</fabrikam:CustomerKey> <fabrikam:ShoppingCart>ABCDEFG</fabrikam:ShoppingCart> </wsa:ReferenceParameters> </wsa:EndpointReference>
El valor de la dirección se copia al bloque de cabecera "To" y los elementos "CustomerKey" y "ShoppingCart" se copian literalmente como bloques de cabecera en un mensaje SOAP dirigido al extremo en cuestión. El mensaje SOAP resultante se vería así:
Ejemplo 3.2. Ejemplo de referencia de extremo convertida en bloques de cabecera de mensaje SOAP.
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:fabrikam="http://example.com/fabrikam"> <S:Header> ... <wsa:To>http://example.com/fabrikam/acct</wsa:To> <wsa:Action>...</wsa:Action> <fabrikam:CustomerKey wsa:IsReferenceParameter='true'>123456789</fabrikam:CustomerKey> <fabrikam:ShoppingCart wsa:IsReferenceParameter='true'>ABCDEFG</fabrikam:ShoppingCart> ... </S:Header> <S:Body> ... </S:Body> </S:Envelope>
Algunos protocolos subyacentes pueden admitir propiedades similares a las propiedades de direccionamiento de mensajes. Por ejemplo, la cabecera reply-to: de los mensajes de correo electrónico es similar a la propiedad de direccionamiento de mensajes [reply endpoint]. Los autores e implementadores de enlaces no deberían presuponer ninguna correspondencia particular entre las propiedades nativas y las propiedades de direccionamiento de mensajes. Por ejemplo, si un mensaje de correo electrónico representa solamente un salto dentro de una ruta que incluye varios saltos, entonces es probable que la cabecera reply-to: sea diferente de la dirección [reply endpoint].
La extensión SOAP 1.1 Addressing 1.0 define un conjunto de bloques de cabecera SOAP que brindan compatibilidad con la característica SOAP 1.2 Addressing 1.0 descrita en Característica SOAP 1.2 Addressing 1.0. Esta extensión de SOAP 1.1 solamente se ofrece a efectos de compatibilidad hacia atrás.
La extensión SOAP 1.1 Addressing 1.0 se identifica con el siguiente URI:
http://www.w3.org/2005/08/addressing/module
La característica SOAP 1.2 Addressing 1.0 (ver 2. Característica SOAP 1.2 Addressing 1.0) define un conjunto de propiedades SOAP y su correspondencia con las propiedades abstractas de direccionamiento de mensaje definidas por la especificación Web Services Addressing 1.0 - Core [WS-Addressing Core]. La extensión SOAP 1.1 Addressing 1.0 usa la representación como conjunto de información XML de las propiedades abstractas de direccionamiento de mensajes definidas en Web Services Addressing 1.0 - Core y enlaza cada ítem de información de elemento a un bloque de cabecera SOAP. La extensión SOAP 1.1 Addressing 1.0 opera según lo descrito en 3. Módulo SOAP 1.2 Addressing 1.0, con las siguientes salvedades:
Cuando se emplea el enlace SOAP 1.1 HTTP, es obligatorio el uso del campo de cabecera de petición HTTP SOAPAction. El valor de campo de la cabecera de petición HTTP SOAPAction DEBE ser el valor de la propiedad [action] encerrado entre comillas o bien el valor vacío "". El último caso permite ocultar la propiedad [action] por medio de mecanismos de seguridad del nivel de SOAP, sin necesidad de añadir consideraciones de seguridad innecesarias en el nivel de transporte. Si SOAPAction tiene cualquier otro valor, se produce un error de cabecera de direccionamiento inválida (ver 6.4.1 Cabecera de direccionamiento inválida).
En el texto siguiente, el término "extremo de respuesta" se refiere a las propiedades [reply endpoint] y [fault endpoint] en conjunto.
Si el valor de la propiedad [destination] es "http://www.w3.org/2005/08/addressing/anonymous", esto no supone ninguna semántica adicional más allá de la que resulta de las reglas definidas más adelante y descritas en Web Services Addressing 1.0 - Core [WS-Addressing Core]. En particular, obsérvese que Web Services Addressing 1.0 - Core [WS-Addressing Core], sección 3.4 exige el uso de este valor en los mensajes enviados a un extremo de respuesta cuya propiedad [address] sea "http://www.w3.org/2005/08/addressing/anonymous".
Cuando se indica "http://www.w3.org/2005/08/addressing/anonymous" como extremo de respuesta, el enlace SOAP 1.1 - HTTP no se modifica.
Cuando se indica "http://www.w3.org/2005/08/addressing/anonymous" como extremo de respuesta y el mensaje es la propiedad http://www.w3.org/2003/05/soap/mep/InboundMessage de una pauta de intercambio de mensajes SOAP petición-respuesta [SOAP 1.2: Adjuntos], entonces todas las respuestas DEBEN ser la propiedad http://www.w3.org/2003/05/soap/mep/OutboundMessage del mismo tipo de pauta de intercambio de mensajes SOAP petición-respuesta [SOAP 1.2: Adjuntos].
Cuando no se indica "http://www.w3.org/2005/08/addressing/anonymous" como extremo de respuesta, entonces el mensaje DEBERÍA ser parte de un enlace que admita la posibilidad de no devolver un envoltorio SOAP en la respuesta HTTP (p. ej., ver [Enlace SOAP 1.1 HTTP, respuesta opcional a petición]). Todo mensaje de respuesta se DEBERÍA enviar usando una conexión separada y con el valor de dirección especificado por el extremo de respuesta. Obsérvese que otras especificaciones PUEDEN definir URI especiales con otros comportamientos (similares al URI anónimo).
Cuando no se indica "http://www.w3.org/2005/08/addressing/anonymous" como extremo de respuesta, entonces las posibles respuestas NO DEBERÍAN ser la propiedad http://www.w3.org/2003/05/soap/mep/OutboundMessage del mismo tipo de pauta de intercambio de mensajes SOAP petición-respuesta [SOAP 1.2: Adjuntos]. Por ejemplo, un enlace SOAP 1.2 HTTP que admita una pauta de intercambio de mensajes unidireccional podría colocar el mensaje de respuesta en una pauta de intercambio de mensajes unidireccional separada y en una petición HTTP separada. Como en SOAP 1.1/HTTP, obsérvese que otras especificaciones PUEDEN definir URI especiales con otros comportamientos (similares al URI anónimo).
Los errores definidos en esta sección se generan cuando se cumple la condición mencionada en el preámbulo de cada subsección.
Los extremos conformes a esta especificación DEBEN incluir en los mensajes de error generados las propiedades de direccionamiento de mensajes obligatorias, serializadas como cabeceras SOAP. Los mensajes de error se correlacionan como respuestas mediante la propiedad [relationship] definida en Web Services Addressing 1.0 - Core [WS-Addressing Core]. Obsérvese que la omisión de la propiedad [message id] en un mensaje de entrada puede afectar la capacidad del receptor de un mensaje de error para correlacionar dicho mensaje con el mensaje que provocó el error. La omisión de las propiedades [fault endpoint] o [reply endpoint] en los mensajes de entrada puede afectar la entrega de los mensajes de error que pudieran generarse.
La propiedad [action] que se indica a continuación designa los mensajes de error WS-Addressing:
http://www.w3.org/2005/08/addressing/fault
Esta acción NO DEBERÍA usarse como valor de acción en mensajes que no transporten errores WS-Addressing.
Los módulos, extensiones y aplicaciones SOAP DEBERÍAN definir valores de [action] especializados para los errores que describan, pero PUEDEN asignar el uso del siguiente valor de [action]:
http://www.w3.org/2005/08/addressing/soap/fault
El valor de [action] indicado anteriormente DEBERÍA usarse para los errores definidos por SOAP, incluidos "version mismatch" (versiones no coincidentes), "must understand" (obligación de entender) y "data encoding unknown" (codificación de datos desconocida).
Cada uno de los errores predefinidos que se enumeran a continuación se define mediante la especificación de valores para las siguientes propiedades abstractas:
[Code] El código de error; el uso del código de error especificado es OBLIGATORIO.
[Subcode] El subcódigo de error; el uso del subcódigo de error especificado es OBLIGATORIO.
[Subsubcode] Un subcódigo de error más específico que puede emplearse como una cualificación adicional al valor de la propiedad [Subcode]; el uso del subcódigo de error especificado es OPCIONAL.
[Reason] El elemento de motivo, en inglés; se RECOMIENDA usar el código de error especificado, pero se PUEDE usar otro texto.
[Details] El elemento de detalle; el uso del elemento de detalle especificado es OBLIGATORIO. Su ausencia supone que no se definen elementos de detalle para el error.
El enlace entre las propiedades de error y los errores SOAP 1.2 es el siguiente:
El valor de la propiedad [Code] se enlaza con el valor del ítem de información de elemento S:Fault/S:Code/S:Value de los errores SOAP.
El valor de la propiedad [Subcode] se enlaza con el valor del ítem de información de elemento S:Fault/S:Code/S:Subcode/S:Value de los errores SOAP.
El valor de la propiedad [Subsubcode] se enlaza con el valor del ítem de información de elemento S:Fault/S:Code/S:Subcode/S:/Subcode/S:Value de los errores SOAP.
El valor de la propiedad [Reason] se enlaza con el valor del ítem de información de elemento S:Fault/S:Reason/S:Text de los errores SOAP.
El valor de la propiedad [Details] se enlaza con el valor del ítem de información de elemento S:Fault/S:Detail de los errores SOAP.
Ejemplo 6.1. Enlace de propiedades de error con mensajes SOAP 1.2.
<S:Envelope> <S:Header> <wsa:Action>http://www.w3.org/2005/08/addressing/fault</wsa:Action> <!-- Se omiten las cabeceras para abreviar. --> </S:Header> <S:Body> <S:Fault> <S:Code> <S:Value>[Code]</S:Value> <S:Subcode> <S:Value>[Subcode]</S:Value> <S:Subcode> <S:Value>[Subsubcode]</S:Value> </S:Subcode> </S:Subcode> </S:Code> <S:Reason> <S:Text xml:lang="en">[Reason]</S:Text> </S:Reason> <S:Detail> [Detail] </S:Detail> </S:Fault> </S:Body> </S:Envelope>
El error SOAP 1.1 es ligeramente menos expresivo que el error SOAP 1.2, y sólo tiene correspondencias para las propiedades [Subcode], [Reason] y [Detail]. El enlace entre estas propiedades y los errores SOAP 1.1 es el siguiente:
El valor de [Subsubcode] o, en su defecto, el valor de [Subcode] se enlaza con el valor del elemento de error SOAP S11:Fault/faultcode.
El valor de la propiedad [Reason] se enlaza con el valor del elemento S11:Fault/faultstring de los errores SOAP.
El detalle de error SOAP 1.1 sólo se usa con errores relacionados con el cuerpo de un mensaje, de modo que no se usa para errores SOAP 1.1 relacionados con el procesamiento de las cabeceras de direccionamiento. En cambio, el valor de la propiedad [Details] se enlaza con el valor de un nuevo bloque de cabecera SOAP wsa:FaultDetail. Se describe a continuación el elemento wsa:FaultDetail:
Cero o más de los elementos definidos en 6.3 Elementos de detalle de error.
Atributos opcionales de extensibilidad, incluidos role y mustUnderstand de SOAP.
Ejemplo 6.2. Enlace de propiedades de error con mensajes SOAP 1.1.
<S11:Envelope> <S11:Header> <wsa:Action>http://www.w3.org/2005/08/addressing/fault</wsa:Action> <wsa:FaultDetail>[Details]</wsa:FaultDetail> <!-- Se omiten otras cabeceras para abreviar. --> </S11:Header> <S11:Body> <S11:Fault> <faultcode>[Subcode] o [Subsubcode]</faultcode> <faultstring xml:lang="en">[Reason]</faultstring> </S11:Fault> </S11:Body> </S11:Envelope>
Las siguientes subsecciones definen un conjunto de elementos que se emplea para transmitir información adicional en los errores descritos en 6.4 Errores predefinidos.
Se describe a continuación el elemento <wsa:ProblemHeaderQName>:
Un QName que representa el nombre del elemento raíz del bloque de cabecera problemático.
Atributos de extensibilidad opcionales, que no afectan el procesamiento.
Se describe a continuación el elemento <wsa:ProblemIRI>:
El IRI que ocasionó el problema.
Atributos de extensibilidad opcionales, que no afectan el procesamiento.
Se describe a continuación el elemento <wsa:ProblemAction>:
Un elemento opcional que indica la propiedad [action] (acción) que ocasionó el problema.
Un elemento opcional que indica el IRI de la SOAPAction que ocasionó el problema.
Elementos de extensibilidad opcionales, que no afectan el procesamiento.
Atributos de extensibilidad opcionales, que no afectan el procesamiento.
Se describe a continuación el elemento <wsa:RetryAfter>:
Este elemento (cuyo contenido es de tipo xs:unsignedLong) indica un tiempo de espera mínimo sugerido expresado en milisegundos antes de retransmitir el mensaje. La omisión de este elemento indica que nunca se intentará repetir la transmisión.
Atributos de extensibilidad opcionales, que no afectan el procesamiento.
Este error corresponde a una cabecera que representa una propiedad de direccionamiento de mensaje WS-Addressing que es inválida y no se puede procesar. El error de validez puede ser estructural o semántico; p. ej., una propiedad [destination] (destino) que no es una IRI o una propiedad [relationship] (relación) que remite a un [message id] (identificador de mensaje) que nunca se envió.
[Code] un QName que representa el valor S:Sender.
[Subcode] un QName que representa el valor wsa:InvalidAddressingHeader.
[Reason] la cadena: "A header representing a Message Addressing Property is not valid and the message cannot be processed" (una cabecera que representa una propiedad de direccionamiento de mensaje WS-Addressing es inválida y no se puede procesar).
[Details] un elemento <wsa:ProblemHeader> que transmite una copia de la cabecera infractora, o bien un elemento <wsa:ProblemHeaderQName> que transmite el QName del elemento raíz de la cabecera infractora.
El error de cabecera de direccionamiento inválida puede circunscribirse más mediante el uso de las propiedades adicionales [Subsubcode] especificadas en las subsecciones que siguen. El uso de estos valores de [Subsubcode] es OPCIONAL.
Especifica que se esperaba que la cabecera inválida fuera una referencia de extremo, pero que ésta no resultó válida.
Especifica que la cantidad de apariciones de la cabecera indicada fue superior a lo esperado.
Especifica que se esperaba que la cabecera inválida fuera una referencia de extremo, pero que ésta no contenía una propiedad [address].
Especifica que la cabecera inválida contenía una propiedad [message id] idéntica a otra que se recibió con anterioridad.
Falta una cabecera obligatoria que representa una propiedad de direccionamiento de mensaje.
[Code] un QName que representa el valor S:Sender.
[Subcode] un QName que representa el valor wsa:MessageAddressingHeaderRequired.
[Reason] la cadena: "A required header representing a Message Addressing Property is not present" (falta una cabecera obligatoria que representa una propiedad de direccionamiento de mensaje).
[Details] un elemento <wsa:ProblemHeaderQName> que transmite el QName de la cabecera de direccionamiento de mensaje faltante.
El extremo identificado por el valor de la propiedad [destination] es inalcanzable.
[Code] un QName que representa el valor S:Sender.
[Subcode] un QName que representa el valor wsa:DestinationUnreachable.
[Reason] la cadena: "No route can be determined to reach [destination]" (no pudo determinarse una ruta a [destination]).
[Details] un elemento <wsa:ProblemIRI> opcional que transmite la propiedad [address] del destino ([destination]).
La implementación de este error es opcional.
La propiedad [action] en el mensaje no está permitida en este extremo.
[Code] un QName que representa el valor S:Sender.
[Subcode] un QName que representa el valor wsa:ActionNotSupported.
[Reason] la cadena: "The [action] cannot be processed at the receiver" (el receptor no puede procesar la propiedad [action]).
[Details] un elemento <wsa:ProblemAction> con un elemento hijo <wsa:Action> OBLIGATORIO.
La implementación de este error es opcional.
El extremo no puede procesar el mensaje en este momento, ya sea debido a algún problema transitorio o a un fallo permanente.
Opcionalmente, el extremo puede incluir un parámetro RetryAfter en el detalle. El origen NO DEBERÍA retransmitir el mensaje antes del tiempo estipulado.
[Code] un QName que representa el valor S:Receiver.
[Subcode] un QName que representa el valor wsa:EndpointUnavailable.
[Reason] la cadena "The endpoint is unable to process the message at this time" (el extremo no puede procesar el mensaje en este momento).
[Details] un elemento <wsa:RetryAfter> opcional y un elemento <wsa:ProblemIRI> opcional que transmite la propiedad [address] del destino ([destination]).
La implementación de este error es opcional.
Observación:
Esta especificación no plantea supuesto alguno respecto de los requisitos de seguridad del nivel de la aplicación, la organización de la aplicación, la implementación de emisores y receptores o de los modos en que otros protocolos puedan utilizar WS-Addressing y de los mecanismos de seguridad que dichos protocolos puedan emplear. Es muy recomendable adoptar un enfoque integral en materia de seguridad, que considere todos los componentes de la aplicación, los otros protocolos empleados, la forma en que estos protocolos se integran con WS-Security y el uso de otros métodos o técnicas adicionales.
Como se explica en Web Services Addressing 1.0 - Core [WS-Addressing Core], WS-Addressing incluye capacidades que le permiten a un emisor de mensaje solicitar al receptor que envíe mensajes adicionales no solicitados a una lista arbitraria de otros receptores y controlar hasta cierto punto el contenido de dichos mensajes mediante el uso de parámetros de referencia. El enlace SOAP de WS-Addressing transforma los parámetros de referencia de extremo en cabeceras SOAP, lo que le permite al emisor del mensaje solicitar al receptor que envíe mensajes SOAP no solicitados a una lista arbitraria de otros receptores y especificar un conjunto de cabeceras SOAP que se deberá incluir en dichos mensajes.
Las cabeceras SOAP son un potente mecanismo de extensión, de modo que se debería tener mucho cuidado antes de acatar las propiedades [reply endpoint] o [fault endpoint], a fin de evitar participar inadvertidamente en las actividades de emisores de mensajes SOAP maliciosos.
Se debería proteger la integridad de las propiedades de direccionamiento de mensaje de WS-Addressing serializadas como cabeceras SOAP (wsa:To, wsa:Action y otras), incluidas las cabeceras que aparecen como resultado de la propiedad [reference parameters], según se explica en Web Services Addressing 1.0 - Core [WS-Addressing Core].
Los mensajes que usen cabeceras wsa:ReplyTo o wsa:FaultTo cuya propiedad [address] no sea el URI anónimo predefinido, deberían incluir pruebas que permitan al receptor confirmar que la referencia de extremo fue emitida por una fuente con autoridad para representar la propiedad [address] de dicha referencia de extremo.
Al recibir un mensaje SOAP pueden encontrarse algunas cabeceras SOAP resultantes de la serialización de la propiedad [reference parameters] de una referencia de extremo. El receptor de un mensaje SOAP debería realizar controles adicionales de seguridad e integridad para evitar acciones no deseadas.
Hay muchos mecanismos que podrían emplearse para ofrecer pruebas de que el emisor de un mensaje tiene autoridad para representar la propiedad [address] de las referencias de extremo provistas dentro del mensaje. Por lo general, dichos mecanismos requieren la inclusión de una cabecera WS-Security [WS-Security] que contenga firmas digitales XML que enlacen los elementos wsa:ReplyTo y wsa:FaultTo al mensaje SOAP mediante una prueba de seguridad emitida por una autoridad en la que el receptor del mensaje confíe en relación con el dominio de la propiedad [address] de la referencia de extremo. La posesión de una prueba de seguridad emitida por una autoridad de confianza para el dominio de la propiedad [address] de la referencia de extremo brinda un nivel de confianza en que el emisor del mensaje tiene autoridad para representar la propiedad [address].
Por ejemplo, un mensaje podría incluir una cabecera WS-Security [WS-Security] que contenga firmas digitales XML que enlacen los elementos wsa:ReplyTo y wsa:FaultTo al mensaje SOAP mediante un certificado X.509 para el dominio direccionado por la propiedad [address] de la referencia de extremo. Si el emisor del certificado es una autoridad de confianza para el receptor del mensaje, entonces éste puede confiar hasta cierto punto en que el emisor del mensaje tiene autoridad para representar la propiedad [address] de la referencia de extremo.
El atributo wsa:isReferenceParameter sólo tiene significado dentro de cabeceras SOAP. Los procesadores de mensajes deberían considerar que su presencia en cualquier otro lugar de un mensaje SOAP es señal de un posible ataque.
Los procesadores de mensajes deberían considerar señal de un posible ataque la presencia de elementos de los espacios de nombres soap11, soap12 y wsa como parámetros de referencia en una referencia de extremo.
Se conocen ciertos ataques de XML ID y reestructuración que los procesadores de mensajes deberían tener en cuenta; ver [WS-Security] - Security Considerations: Removal and modification of XML elements.
Para evitar la violación de firmas, los intermediarios NO DEBEN modificar la representación XML de las cabeceras WS-Addressing que retransmitan. En concreto, los intermediarios NO DEBEN eliminar contenido XML que indique explícitamente valores que en su defecto serían implícitos, y NO DEBEN insertar contenido XML para volver explícitos los valores implícitos. Por ejemplo, si hay un atributo RelationshipType con el valor "http://www.w3.org/2005/08/addressing/reply", un intermediario NO DEBE eliminarlo; del mismo modo, si no hay un atributo RelationshipType, el intermediario NO DEBE añadirlo.
Un mensaje SOAP 1.2 es conforme al módulo SOAP 1.2 Addressing 1.0 cuando contiene cabeceras del espacio de nombres wsa y respeta todas las restricciones sobre las propiedades de direccionamiento de mensajes definidas por Web Services Addressing 1.0 - Core [WS-Addressing Core] y por el módulo SOAP 1.2 Addressing 1.0.
Un mensaje SOAP 1.1 es conforme a la extensión SOAP 1.1 Addressing 1.0 cuando contiene cabeceras del espacio de nombres wsa y respeta todas las restricciones sobre las propiedades de direccionamiento de mensajes definidas por Web Services Addressing 1.0 - Core [WS-Addressing Core] y por la extensión SOAP 1.1 Addressing 1.0.
Un extremo conforme a esta especificación entiende y acepta mensajes SOAP que contienen cabeceras en el espacio de nombres wsa dirigidas a dicho extremo, y genera los mensajes de respuesta o error que pueda enviar como respuesta de acuerdo a las reglas descritas en esta especificación y en Web Services Addressing 1.0 - Core [WS-Addressing Core].
Observación:
En el enlace Web Services Addressing 1.0 - WSDL [Enlace WS-Addressing WSDL] se describen los requisitos de conformidad adicionales para la descripción de un extremo.
Observación:
Los extremos PUEDEN aceptar y responder mensajes que no contengan cabeceras WSA.
Si un receptor procesa un mensaje que contiene una cabecera wsa:Action, este enlace SOAP entra en vigencia y deben cumplirse las reglas de esta especificación.
Este documento es obra del Grupo de trabajo para el direccionamiento de servicios web del W3C.
Los miembros del grupo de trabajo son (al momento de redactarse este documento y por orden alfabético): Abbie Barbir (Nortel Networks), Andreas Bjärlestam (ERICSSON), Dave Chappell (Sonic Software), Eran Chinthaka (WSO2), Francisco Curbera (IBM Corporation), Glen Daniels (Sonic Software), Vikas Deolaliker (Sonoa Systems, Inc.), Paul Downey (BT), Jacques Durand (Fujitsu Limited), Robert Freund (Hitachi, Ltd.), Marc Goodner (Microsoft Corporation), Arun Gupta (Sun Microsystems, Inc.), Hugo Haas (W3C/ERCIM), Marc Hadley (Sun Microsystems, Inc.), David Hull (TIBCO Software, Inc.), Yin-Leng Husband (HP), David Illsley (IBM Corporation), Anish Karmarkar (Oracle Corporation), Paul Knight (Nortel Networks), Philippe Le Hégaret (W3C/MIT), Amelia Lewis (TIBCO Software, Inc.), Bozhong Lin (IONA Technologies, Inc.), Mark Little (JBoss Inc.), Jonathan Marsh (Microsoft Corporation), Jeff Mischkinsky (Oracle Corporation), Nilo Mitra (ERICSSON), Eisaku Nishiyama (Hitachi, Ltd.), Ales Novy (Systinet Inc.), David Orchard (BEA Systems, Inc.), Gilbert Pilz (BEA Systems, Inc.), Alain Regnier (Ricoh Company, Ltd.), Tony Rogers (Computer Associates), Tom Rutt (Fujitsu Limited), Davanum Srinivas (WSO2), Jiri Tejkl (Systinet Inc.), Mike Vernal (Microsoft Corporation), Steve Vinoski (IONA Technologies, Inc.), Katy Warr (IBM Corporation), Pete Wenzel (Sun Microsystems, Inc.), Steve Winkler (SAP AG), Ümit Yalçinalp (SAP AG), Prasad Yendluri (webMethods, Inc.).
Otros miembros anteriores del grupo de trabajo fueron: Lisa Bahler (SAIC - Telcordia Technologies), Rebecca Bergersen (IONA Technologies, Inc.), Ugo Corda (Sun Microsystems, Inc.), Michael Eder (Nokia), Yaron Goland (BEA Systems, Inc.), Marc Goodner (SAP AG), Martin Gudgin (Microsoft Corporation), Mark Nottingham (BEA Systems, Inc.), Mark Peel (Novell, Inc.), Harris Reynolds (webMethods, Inc.), Rich Salz (IBM Corporation), Davanum Srinivas (Computer Associates), Greg Truty (IBM Corporation).
Agradecemos además a las personas que contribuyeron en los debates en la lista pública public-ws-addressing@w3.org.