1SOAP::WSDL::Manual::CooUksbeorokC(o3n)tributed Perl DocuSmOeAnPt:a:tWiSoDnL::Manual::Cookbook(3)
2
3
4
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
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
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
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
261 Martin Kutter <martin.kutter fen-net.de>
262
264 $Rev: 583 $
265 $LastChangedBy: kutterma $
266 $Id: $
267 $HeadURL: $
268
269
270
271perl v5.34.0 2021-07-22 SOAP::WSDL::Manual::Cookbook(3)