Web Service Metadata Exchange http msdn microsoft comws200402mex
Web Service Metadata Exchange (http: //msdn. microsoft. com/ws/2004/02/mex) David Aiken (7/4/04) 11/25/2020 1
Introduction 11/25/2020 • This specification defines messages to retrieve specific types of metadata associated with an endpoint. • Uses XML, SOAP(1. 1, 1. 2) and WSDL(1. 1) extensibility models. • Web services specifications (WS-*) are designed to be composed with each other to provide a rich set of tools to provide security in the Web services environment. • This specification specifically relies on other Web services specifications to provide secure, reliable, and/or transacted message delivery and to express Web service and client policy. 2
Web Services • Web services use metadata to describe what other endpoints need to know to interact with them. - WS-Policy describes the capabilities, requirements and general characteristics of Web services. - WSDL(1. 1) describes abstract message operations, concrete network protocols, and endpoint addresses used by Web services. - XML Schema(part 1, part 2) describes the structure and contents of XML-based messages received and sent by Web services. • To bootstrap communication with a Web service, this specification defines three request/response message pairs to retrieve these three types of metadata 1) WS-Policy & receiving endpoint or target namespace. 2) WSDL & receiving endpoint or target namespace. 3) XML Schema with a given target namespace. • 11/25/2020 Examples…. 3
Terminology • Key words(S. Bradner’s paper RFC 2119); MUST: absolute requirement of the specification. SHOULD: there may exist valid reasons in particular circumstances to ignore a particular item. MAY: an item is truly optional. • • • Anything in Italics indicate data types not values. ? = 0 or 1. * = 0 or more. + = 1 or more. [] = items inside are to be treated as groups wrt cardinality or choice. … = a point of extensibility allowing more attributes. • Prefix s s 11 S 12 wsa wsdl wsse wsp wsx xs 11/25/2020 Prefix XML Namespace Specification(s) XML namespace Specifications (Either SOAP 1. 1 or 1. 2) http: //schemas. xmlsoap. org/soap/envelope SOAP 1. 1 [SOAP 1. 1] http: //www. w 3. org/2003/05/soap-envelope SOAP 1. 2 [SOAP 1. 2] http: //schemas. xmlsoap. org/ws/2004/03/addressing WS-Addressing [WSAddressing] http: //schemas. xmlsoap. org/wsdl/ WSDL [WSDL 1. 1] http: //schemas. xmlsoap. org/ws/2002/12/secext WS- Security. Policy [WSSecurity. Policy] http: //schemas. xmlsoap. org/ws/2002/12/policy WS-Policy [WS-Policy] http: //schemas. xmlsoap. org/ws/2004/03/mex WS-Metadata Exchange http: //www. w 3. org/2001/XMLSchema XML Schema [Part 1, 2] 4
Example 1 Get Policy Request • • • • • • 11/25/2020 (01) <s 12: Envelope (02) xmlns: s 12='http: //www. w 3. org/2003/05/soap-envelope' (03) xmlns: wsa='http: //schemas. xmlsoap. org/ws/2004/03/addressing' (04) xmlns: wsx='http: //schemas. xmlsoap. org/ws/2004/03/mex' > (05) <s 12: Header> (06) <wsa: Action> (07) http: //schemas. xmlsoap. org/ws/2004/03/mex/Get. Policy/Request (08) </wsa: Action> (09) <wsa: Message. ID> (10) uuid: 73 d 7 edfc-5 c 3 c-49 b 9 -ba 46 -2480 caee 43 e 9 (11) </wsa: Message. ID> (12) <wsa: Reply. To> (13) <wsa: Address>http: //www. example. com/My. Endpoint</wsa: Address> (14) </wsa: Reply. To> (15) <wsa: To> http: //www. example. org/Your. Endpoint</wsa: To> (16) <ex: My. Ref. Prop xmlns: ex='http: //www. example. com/refs' > (17) 78 f 2 dc 229597 b 529 b 81 c 4 bef 76453 c 96 (18) </ex: My. Ref. Prop> (19) </s 12: Header> (20) <s 12: Body> (21) <wsx: Get. Policy /> (22) </s 12: Body> (23) </s 12: Envelope> 5
Example 1 Get Policy Request • • • 11/25/2020 Lines(6 -8): indicate that this is a Get Policy request Lines(10): is the Message. ID for this request. Lines(15 -18): illustrate a typical pattern where the endpoint is identified by a wsa: To header block (15) as well as an application-specific header block(16 -18) Line(21) could alternatively include a target namespace instead of the associated receiving endpoint. Now to respond to the Get Policy Request… 6
Example 2 Get Policy Response • • • • • • • • 11/25/2020 (01) <s 12: Envelope (02) xmlns: s 12='http: //www. w 3. org/2003/05/soap-envelope' (03) xmlns: wsa='http: //schemas. xmlsoap. org/ws/2004/03/addressing' (04) xmlns: wsp='http: //schemas. xmlsoap. org/ws/2002/12/policy' (05) xmlns: wsx='http: //schemas. xmlsoap. org/ws/2004/03/mex' > (06) <s 12: Header> (07) <wsa: Action> (08) http: //schemas. xmlsoap. org/ws/2004/03/mex/Get. Policy/Response (09) </wsa: Action> (10) <wsa: Relates. To> (11) uuid: 73 d 7 edfc-5 c 3 c-49 b 9 -ba 46 -2480 caee 43 e 9 (12) </wsa: Relates. To> (13) <wsa: To>http: //www. example. com/My. Endpoint</wsa: To> (14) </s 12: Header> (15) <s 12: Body> (16) <wsx: Get. Policy. Response> (17) <wsp: Policy (18) xmlns: wsse='http: //schemas. xmlsoap. org/ws/2002/12/secext' > (19) <wsp: One. Or. More> (20) <wsse: Security. Token wsp: Usage='wsp: Required' (21) wsp: Preference='100' > (22) <wsse: Token. Type>wsse: Kerberosv 5 TGT</wsse: Token. Type> (23) </wsse: Security. Token> (24) <wsse: Security. Token wsp: Usage='wsp: Required' (25) wsp: Preference='1' > (26) <wsse: Token. Type>wsse: X 509 v 3</wsse: Token. Type> (27) </wsse: Security. Token> (28) </wsp: One. Or. More> (29) </wsp: Policy> (30) </wsx: Get. Policy. Response> (31) </s 12: Body> (32) </s 12: Envelope> 7
Example 2 Get Policy Response Lines(7 -9): says this message is a response to a Get Policy Request. Lines(10 -12): this response is to the specific request (Message. ID) we have just sent. Lines(17 -29): contains the Policy corresponding to the receiver. 11/25/2020 8
Retrieving Metadata 11/25/2020 • - Retrieving Policy: A requestor MAY send a Get Policy Request message to an endpoint. If an endpoint accepts a Get Policy Request, it MUST reply with a Get Policy Response. • - Retrieving WSDL: A requestor MAY send a Get WSDL Request message to an endpoint. If an endpoint accepts a Get WSDL Request, it MUST reply with a Get WSDL Response. • - Retrieving Schema: A requestor MAY send a Get Schema Request message to an endpoint. If an endpoint accepts a Get Schema Request, it MUST reply with a Get Schema Response. 9
General outline Get WSDL Request (1) • • • • <s: Envelope. . . > <s: Header. . . > <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/03/mex/Get. WSDL/Request </wsa: Action> <wsa: Message. ID>xs: any. URI</wsa: Message. ID> ? <wsa: Reply. To>endpoint-reference</wsa: Reply. To> ? <wsa: To>xs: any. URI</wsa: To>. . . </s: Header> <s: Body. . . > <wsx: Get. WSDL. . . > <wsx: Target. Namespace>xs: any. URI</wsx: Target. Namespace> ? </wsx: Get. WSDL> </s: Body> </s: Envelope> 0 or more Action: MUST be included to define the metadata to be returned. Reply. To: if included MUST be of type wsa: Endpointreference. Type. Target. Namespace: request is for WSDL documents in the indicated target namespace. 11/25/2020 10
General outline Get WSDL Response (2) • • • • <s: Envelope. . . > <s: Header. . . > <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/03/mex/Get. WSDL/Response </wsa: Action> <wsa: Relates. To>xs: any. URI</wsa: Relates. To> ? <wsa: To>xs: any. URI</wsa: To>. . . extensibility </s: Header> <s: Body. . . > <wsx: Get. WSDLResponse> <wsdl: definitions. . . >. . . </wsdl: definitions> + 1 or more </wsx: Get. WSDLResponse> </s: Body> </s: Envelope> Action: MUST be included in the response message. Relates. To: header block MUST be included and MUST have that value (MAY include a Message. ID). definitions: SHOULD be repeated if there is > 1 WSDL in the target namespace 11/25/2020 11
Faults (1) • No WSDL If the receiver does not have a WSDL for the specified target namespace, the request MUST fail and the receiver MAY generate a SOAP fault as follows: SOAP 1. 1: -faultcode = s 11: client -faultstring = e. g. , “unknown target namespace” SOAP 1. 2: -s 12: Code/s 12: value = s 12: Sender -s 12: Code/s 12: Subcode/s 12: Value = wsx: Unkown. Target. Namespace -s 12: Reason/s 12: Text = e. g. , “unknown target namespace” 11/25/2020 12
Faults (2) • Exposure If the receiver does not expose WSDL for itself, the request MUST fail, and the receiver MAY generate a SOAP fault as follows: SOAP 1. 1: -faultcode = s 11: client -faultstring = e. g. , “WSDL unavailable for endpoint” SOAP 1. 2: -s 12: Code/s 12: value = s 12: Sender -s 12: Code/s 12: Subcode/s 12: Value = wsx: WSDLUnavailable -s 12: Reason/s 12: Text = e. g. , “WSDL unavailable for endpoint” 11/25/2020 13
General outline for Get Policy Request/Response • have already have seen a working example for this. • The faults would simply reply; -If receiver does not have Policy for the specified target namespace, SOAP 1. 1: -faultstring = e. g. , “unknown target namespace” SOAP 1. 2: -s 12: Code/s 12: Subcode/s 12: Value = wsx: Unkown. Target. Namespace -s 12: Reason/s 12: Text = e. g. , “unknown target namespace” -If receiver does not expose policy for itself, SOAP 1. 1: -faultstring = e. g. , “policy unavailable for endpoint” SOAP 1. 2: -s 12: Code/s 12: Subcode/s 12: Value = wsx: Unkown. Target. Namespace -s 12: Reason/s 12: Text = e. g. , “unknown target namespace” 11/25/2020 14
General outline Get Schema Request (1) • • • • <s: Envelope. . . > <s: Header. . . > <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/03/mex/Get. Schema/Request </wsa: Action> <wsa: Message. ID>xs: any. URI</wsa: Message. ID> ? <wsa: Reply. To>endpoint-reference</wsa: Reply. To> ? <wsa: To>xs: any. URI</wsa: To>. . . </s: Header> <s: Body. . . > <wsx: Get. Schema. . . > <wsx: Target. Namespace>xs: any. URI</wsx: Target. Namespace> ? </wsx: Get. Schema> </s: Body> </s: Envelope> Action: MUST be included to define the metadata to be returned. Reply. To: if included MUST be of type wsa: Endpointreference. Type. Target. Namespace: the target namespace of the desired XML Schema. 11/25/2020 15
General outline Get Schema Response (2) • • • • <s: Envelope. . . > <s: Header. . . > <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/03/mex/Get. Schema/Response </wsa: Action> <wsa: Relates. To>xs: any. URI</wsa: Relates. To> ? <wsa: To>xs: any. URI</wsa: To>. . . </s: Header> <s: Body. . . > <wsx: Get. Schema. Response> <xs: schema…>. . . </xs: schema> + </wsx: Get. Schema. Response> </s: Body> </s: Envelope> Action: MUST be included in the response message. Relates. To: header block MUST be included and MUST have that value (MAY include a Message. ID). schema: SHOULD be repeated if there is > 1 XML Schema in the target namespace. 11/25/2020 16
Fault • No Schema If the receiver does not have a schema for the specified target namespace, the request MUST fail and the receiver MAY generate a SOAP fault as follows: SOAP 1. 1: -faultcode = s 11: client -faultstring = e. g. , “unknown target namespace” SOAP 1. 2: -s 12: Code/s 12: value = s 12: Sender -s 12: Code/s 12: Subcode/s 12: Value = wsx: Unkown. Target. Namespace -s 12: Reason/s 12: Text = e. g. , “unknown target namespace” • 11/25/2020 Unsure as to why there is no documentation on a receiver that does not expose its Schema!? 17
Other Faults (1) • If a get Policy, Get WSDL or Get Schema does not comply with the outlines we have just covered, the request MUST fail, and the receiver MAY generate a SOAP faults as follows; SOAP 1. 1: -faultcode = s 11: client -faultstring = e. g. , “message is invalid” SOAP 1. 2: -s 12: Code/s 12: value = s 12: Sender -s 12: Code/s 12: Subcode/s 12: Value = wsx: Invalid. Request -s 12: Reason/s 12: Text = e. g. , “message is invalid” 11/25/2020 18
Other Faults (2) • If the amount of data to be sent in a get Policy, Get WSDL or Get Schema response exceeds what the receiver can include, the request MUST fail, and the receiver MAY generate a SOAP faults as follows; SOAP 1. 1: -faultcode = s 11: client -faultstring = e. g. , “response is too large” SOAP 1. 2: -s 12: Code/s 12: value = s 12: Receiver -s 12: Code/s 12: Subcode/s 12: Value = wsx: Response. Too. Large -s 12: Reason/s 12: Text = e. g. , “response is too large” 11/25/2020 19
Normative Protocol Binding 11/25/2020 • A binding for the messages, SOAP(1. 1) over http as constrained by the Basic Profile(1. 0) is recommended as a means to bootstrap communication. • A web service if free to support these messages over other bindings in addition to , or in place of, the WSDL(1. 1) binding. • If no other binding is explicitly stated then the default binding is assumed to be SOAP over http. 20
Conclusions 11/25/2020 • We saw a working example of a Get Policy Request/Response. • Also general outlines of Get WSDL and Get Schema including their faults • It is strongly recommended that the communication between web Services be secured using the mechanisms described in WS-Security…. (presentation? ) 21
- Slides: 21