1SOAP::WSDL::Manual::CooUksbeorokC(o3n)tributed Perl DocuSmOeAnPt:a:tWiSoDnL::Manual::Cookbook(3)
2
3
4

NAME

6       SOAP::WSDL::Manual::Cookbook - SOAP::WSDL recipes
7
8   Accessing HTTPS webservices
9       You need Crypt::SSLeay installed to access HTTPS webservices.
10
11   Accessing protected web services
12       Passing a username and password, or a client certificate and key, to
13       the transport layer is highly dependent on the transport backend. The
14       descriptions below are for HTTP(S) transport using LWP::UserAgent
15
16       Accessing HTTP(S) webservices with basic/digest authentication
17
18       When using SOAP::WSDL::Transport::HTTP (SOAP::Lite not installed), add
19       a method called "get_basic_credentials" to SOAP::WSDL::Transport::HTTP:
20
21        *SOAP::WSDL::Transport::HTTP::get_basic_credentials = sub {
22           return ($user, $password);
23        };
24
25       When using SOAP::Transport::HTTP (SOAP::Lite is installed), do the same
26       to this backend:
27
28        *SOAP::Transport::HTTP::Client::get_basic_credentials = sub {
29            return ($user, $password);
30        };
31
32       Accessing HTTP(S) webservices protected by NTLM authentication
33
34       If you want to connect to a windows server using some Windows Domain
35       Login, please consider using Kerberos instead of the (older) NTLM
36       mechanism - see below.
37
38       Kerberos and NTLM are (currently) mutually exclusive - when
39       LWP::Authen::Negotiate is installed, it will always be queried (and
40       will always raise an error), even if you don't want to use it. See
41       http://rt.cpan.org/Public/Bug/Display.html?id=32826 for details.
42
43       You need the NTLM distribution installed to access webservices
44       protected by NTLM authentication. More specifically, you need the
45       Authen::NTLM module from this distribution. Note that this is different
46       from the Authen::NTML distribution by Yee Man Chan also available from
47       CPAN.
48
49       Your user credentials usually need to include the windows domain or the
50       windows hostname like this:
51
52        testdomain\testuser
53
54       or
55
56        \\testhost\testuser
57
58       Besides passing user credentials as when accessing a web service
59       protected by basic or digest authentication, you also need to enforce
60       connection keep_alive on the transport backens.
61
62       To do so, pass a proxy argument to the new() method of the generated
63       class. This unfortunately means that you have to set the endpoint URL,
64       too:
65
66        my $interface = MyInterfaces::SERVICE_NAME::PORT_NAME->new({
67            proxy => [ $url, keep_alive => 1 ]
68        });
69
70       You may, of course, decide to just hack the generated class. Be advised
71       that subclassing might be a more appropriate solution - re-generating
72       overwrites changes in interface classes.
73
74       Accessing HTTP(S) webservices protected by NTLMv2
75
76       There are different variants of NTLM, and by default Authen::NTLM uses
77       the v1 variant.
78
79       NTLM is a connection-based handshake authentication protocol, which
80       requires three or more requests on the same connection:
81
82           Request    POST
83           Response   401 Unauthorized
84                      WWW-Authenticate: NTLM
85
86           Request    Authorization: NTLM <base64-encoded type-1-message>
87           Response   401 Unauthorized
88                      WWW-Authenticate: NTLM <base64-encoded type-2-message>
89
90           Request    Authorization: NTLM <base64-encoded type-3-message>
91           Response   200 Ok
92
93       If you try to access a NTLMv2 protected web service and switch on
94       LWP::Debug by saying
95
96        use LWP::Debug qw(+);
97
98       you should see at least two lines containing something like
99
100        Authorization NTLM TlRMTVNTUAABAAAAB7IAAAAAAAAAAAAAAwADACAAAABmb28=
101        ...
102        Authorization NTLM TlRMTVNTUAABAAAAB7IAAAAAAAAAAAAAAw ... much longer ... ADACAAAABmb28=
103
104       If you're talking to a Server using NTLMv2 exclusively, you will only
105       the first line in the debug output, and then an error.
106
107       To explicitly enable NTLMv2, do the following in your client:
108
109        use Authen::NTLM;
110        ntlmv2(1);
111
112       This globally enables the use of NTLMv2. Note that this is a global
113       setting: All clients running in the same perl interpreter will be
114       affected. This can cause unexpected issues when running under mod_perl.
115
116       Accessing webservices protected by HTTP Kerberos Authentication
117
118       Use the LWP::Authen::Negotiate plugin from CPAN. You need to set up
119       GSSAPI to perform the Kerberos authentication, though. How to do this
120       is implementation specific (MIT or Heimdahl). See your Kerberos/GSSAPI
121       documentation for details.
122
123       (Newer) Windows Web Services usually allow one to use both the
124       Negotiate (Kerberos) and NTLM authentication scheme.
125
126       Accessing HTTPS webservices protected by certificate authentication
127
128       You need Crypt::SSLeay installed to access HTTPS webservices.
129
130       See Crypt::SSLeay on how to configure client certificate
131       authentication.
132

XML OUTPUT

134   Outputting namespaces as prefixes
135       Q: I need to interface with a SOAP server which doesn't accept the
136       following format:
137
138        <SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
139            xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
140            <SOAP-ENV:Body>
141                <getElement xmlns="http://services.company.com/">
142                    <elementId>12345</elementId>
143                </getElement>
144            </SOAP-ENV:Body>
145        </SOAP-ENV:Envelope>
146
147       Instead, it requires this:
148
149        <SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
150            xmlns:ns2="http://services.company.com/"
151            xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
152            <SOAP-ENV:Body>
153                <ns2:getElement>
154                    <ns2:elementId>12345</ns2:elementId>
155                </ns2:getElement>
156            </SOAP-ENV:Body>
157        </SOAP-ENV:Envelope>
158
159       How do I do this using SOAP::WSDL?
160
161       A: The following steps are necessary to achieve this result:
162
163       First, you would need to write a new serializer, which is quite easy,
164       as it just creates the envelope and calls ->serialize_qualified() on
165       $header and $body to fill them in. The new serializer has to declare
166       all namespace prefixes used, the rest is just the same as the original
167       XSD serializer.
168
169       Second, you'd need to overwrite the start_tag method in
170       SOAP::WSDL::XSD::Typelib::Element to use the appropriate prefixes for
171       the body elements.
172
173       In contrast to the original method, it would probably look up the
174       appropriate prefix from some data set in the serializer class, so this
175       could be the appropriate place to load
176       SOAP::WSDL::XSD::Typelib::Element and override the method.
177
178       Something like this should do (without the handling of specialties like
179       empty or nil elements):
180
181        %PREFIX_OF = { 'http://services.company.com/' => 'ns2' };
182
183        *SOAP::WSDL::XSD::Typelib::Element::start_tag = sub {
184            # use prefix instead of xmlns attribute and copy the rest from
185            # SOAP::WSDL::XSD::Typelib::Element::start_tag
186            my $prefix = $PREFIX_OF{ $_[0]->get_xmlns() };
187            my $name = $_[1]->{ name } || $self->__get_name();
188            return "<$prefix:$name>";
189        }
190

Skipping unknown XML elements - "lax" XML processing

192       SOAP::WSDL's default serializer SOAP::WSDL::Deserializer::XSD is a
193       "strict" XML processor in the sense that it throws an exception on
194       encountering unknown XML elements.
195
196       SOAP::WSDL::Deserializer::XSD allows switching off the stric XML
197       processing by passing the "strict => 0" option.
198
199   Disabling strict XML processing in a Client
200       Pass the following as "deserializer_args":
201
202        { strict => 0 }
203
204       Example: The generated SOAP client is assumed to be
205       "MyInterface::Test".
206
207        use MyInterface::Test;
208
209        my $soap = MyInterface::Test->new({
210            deserializer_args => { strict => 0 }
211        });
212
213        my $result = $soap->SomeMethod();
214
215   Disabling strict XML processing in a CGI based server
216       You have to set the deserializer in the transport class explicitly to a
217       SOAP::WSDL::Deserializer object with the "strict" option set to 0.
218
219       Example: The generated SOAP server is assumed to be "MyServer::Test".
220
221        use strict;
222        use MyServer::Test;
223        use SOAP::WSDL::Deserializer::XSD;
224
225        my $soap = MyServer::Test->new({
226            transport_class => 'SOAP::WSDL::Server::CGI',
227            dispatch_to => 'main',
228        });
229        $soap->get_transport()->set_deserializer(
230           SOAP::WSDL::Deserializer::XSD->new({ strict => 0 })
231        );
232
233        $soap->handle();
234
235   Disabling strict XML processing in a mod_perl based server
236       Sorry, this is not implemented yet - you'll have to write your own
237       handler class based on SOAP::WSDL::Server::Mod_Perl2.
238

Changing the encoding of a SOAP request

240       SOAP::WSDL uses utf-8 per default: utf-8 is the de-facto standard for
241       webservice ommunication.
242
243       However, you can change the encoding the transport layer announces by
244       calling "set_encoding($encoding)" on a client object.
245
246       You probably have to write your own serializer class too, because the
247       default serializer has the utf-8 encoding hardcoded in the envelope.
248
249       Just look into SOAP::WSDL::Serializer on how to do that.
250
251       Don't forget to register your serializer at the serializer factory
252       SOAP::WSDL::Factory::Serializer.
253

255       Copyright 2008, 2009 Martin Kutter.
256
257       This file is part of SOAP-WSDL. You may distribute/modify it under the
258       same terms as perl itself.
259

AUTHOR

261       Martin Kutter <martin.kutter fen-net.de>
262

REPOSITORY INFORMATION

264        $Rev: 583 $
265        $LastChangedBy: kutterma $
266        $Id: $
267        $HeadURL: $
268
269
270
271perl v5.32.1                      2021-01-27   SOAP::WSDL::Manual::Cookbook(3)
Impressum