A minimal node SOAP client with ntlm authentication
npm install soap-ntlmThis module lets you connect to web services using SOAP. It also provides a server that allows you to run your own SOAP services.
* Very simple API
* Handles both RPC and Document schema types
* Supports multiRef SOAP messages (thanks to @kaven276)
* Support for both synchronous and asynchronous method handlers
* WS-Security (currently only UsernameToken and PasswordText encoding is supported)
Install with npm:
``
npm install soap-ntlmModule
` javascript
var soap = require('soap-ntlm');
var fs = require('fs');
var httpntlm = require('httpntlm');
var url = 'https://domain.com/sites/STS20141125160011/_vti_bin/TaxonomyClientService.asmx?wsdl';
var username = 'username';
var password = 'pass';
httpntlm.get({
url: url,
password: password,
username: username
}, function(err, wsdl){
fs.writeFile('taxonomy.wsdl', wsdl.body, function(){
soap.createClient(__dirname+'/taxonomy.wsdl', function(err, client) {
if(err){
console.log(err);
return;
}
client.setSecurity(new soap.NtlmSecurity(username, password));
//works like autocomplete input
client.GetTermsByLabel({
label: 'Work', //find labels that contains word 'work' - case insensitive
lcid: 1033, //language = 'en_us'
matchOption: 'StartsWith',
resultCollectionSize: 5, // looks like server don't care - always sends 20 element
addIfNotFound: false
}, function(err, res){
//parseString(res.GetTermsByLabelResult, function(err, obj){
// console.log(obj);
//});
});
});
});
});
`
Within the options object you may provide an endpoint property in case you want to override the SOAP service's host specified in the .wsdl file.
` javascript
var myService = {
MyService: {
MyPort: {
MyFunction: function(args) {
return {
name: args.name
};
}
// This is how to define an asynchronous function.
MyAsyncFunction: function(args, callback) {
// do some work
callback({
name: args.name
})
}
}
}
}
var xml = require('fs').readFileSync('myservice.wsdl', 'utf8'),
server = http.createServer(function(request,response) {
response.end("404: Not Found: "+request.url)
});
server.listen(8000);
soap.listen(server, '/wsdl', myService, xml);
`
If the log method is defined it will be called with 'received' and 'replied'
along with data.
` javascript`
server = soap.listen(...)
server.log = function(type, data) {
// type is 'received' or 'replied'
};
If server.authenticate is not defined no authentation will take place.
` javascript`
server = soap.listen(...)
server.authenticate = function(security) {
var created, nonce, password, user, token;
token = security.UsernameToken, user = token.Username,
password = token.Password, nonce = token.Nonce, created = token.Created;
return user === 'user' && password === soap.passwordDigest(nonce, created, 'password');
};
This is called prior to soap service method
If the method is defined and returns false the incoming connection is
terminated.
` javascript`
server = soap.listen(...)
server.authorizeConnection = function(req) {
return true; // or false
};
An instance of Client is passed to the soap.createClient callback. It is used to execute methods on the soap service.
` javascript`
client.describe() // returns
{
MyService: {
MyPort: {
MyFunction: {
input: {
name: 'string'
}
}
}
}
}
has several default security protocols. You can easily add your own
as well. The interface is quite simple. Each protocol defines 2 methods:
* addOptions - a method that accepts an options arg that is eventually passed directly to request
* toXML - a method that reurns a string of XML.By default there are 3 protocols:
####BasicAuthSecurity
javascript
client.setSecurity(new soap.BasicAuthSecurity('username', 'password'));
`####ClientSSLSecurity
_Note_: If you run into issues using this protocol, consider passing these options
as default request options to the constructor:
* rejectUnauthorized: false
* strictSSL: false
* secureOptions: constants.SSL_OP_NO_TLSv1_2//this is likely needed for node >= 10.0
javascript
client.setSecurity(new soap.ClientSSLSecurity(
'/path/to/key'
, '/path/to/cert'
, {/default request options/}
));
`####WSSecurity
javascript
client.setSecurity(new soap.WSSecurity('username', 'password'))
`####BearerSecurity
javascript
client.setSecurity(new soap.BearerSecurity('token'));
`$3
javascript
client.MyFunction({name: 'value'}, function(err, result, raw, soapHeader) {
// result is a javascript object
// raw is the raw response
// soapHeader is the response soap header as a javascript object
})
`
$3
javascript
client.MyService.MyPort.MyFunction({name: 'value'}, function(err, result) {
// result is a javascript object
})
`
#### Options (optional)
- Accepts any option that the request module accepts, see here.
- For example, you could set a timeout of 5 seconds on the request like this:
javascript
client.MyService.MyPort.MyFunction({name: 'value'}, function(err, result) {
// result is a javascript object
}, {timeout: 5000})
`$3
#### Options -
Object({rootName: {name: "value"}}) or strict xml-string##### Optional parameters when first arg is object :
-
name Unknown parameter (it could just a empty string)
- namespace prefix of xml namespace
- xmlns URI$3
WSSecurity
WSSecurity implements WS-Security. UsernameToken and PasswordText/PasswordDigest is supported. An instance of WSSecurity is passed to Client.setSecurity.
` javascript
new WSSecurity(username, password, passwordType)
//'PasswordDigest' or 'PasswordText' default is PasswordText
`Handling XML Attributes, Value and XML (wsdlOptions).
Sometimes it is necessary to override the default behaviour of in order to deal with the special requirements
of your code base or a third library you use. Therefore you can use the wsdlOptions Object, which is passed in the
#createClient() method and could have any (or all) of the following contents:
`javascript
var wsdlOptions = {
attributesKey: 'theAttrs',
valueKey: 'theVal',
xmlKey: 'theXml'
}
`
If nothing (or an empty Object ) is passed to the #createClient() method, the node-soap defaults (attributesKey: 'attributes', valueKey: '$value' and xmlKey: '$xml') are used.###Overriding the
value key
By default, node-soap uses $value as key for any parsed XML value which may interfere with your other code as it
could be some reserved word, or the $ in general cannot be used for a key to start with.You can define your own
valueKey by passing it in the wsdl_options to the createClient call like so:
`javascript
var wsdlOptions = {
valueKey: 'theVal'
};soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
// your code
});
`###Overriding the
key
As valueKey, node-soap uses $xml as key. The xml key is used to pass XML Object without adding namespace or parsing the string.Example :
`javascript
dom = {
$xml: '
};
`xml
`You can define your own
by passing it in the wsdl_options to the createClient call like so:
`javascript
var wsdlOptions = {
xmlKey: 'theXml'
};soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
// your code
});
`###Overriding the
key
You can achieve attributes like:
` xml
`
By attaching an attributes object to a node.
javascript
{
parentnode: {
childnode: {
attributes: {
name: 'childsname'
}
}
}
}
`
However, "attributes" may be a reserved key for some systems that actually want a node
xml
`In this case you can configure the attributes key in the
like so.
`javascript
var wsdlOptions = {
attributesKey: '$attributes'
};soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
client.method({
parentnode: {
childnode: {
$attributes: {
name: 'childsname'
}
}
}
});
});
`Handling "ignored" namespaces
If an Element in a definition depends on an Element which is present in the same namespace, normally the tns:
namespace prefix is used to identify this Element. This is not much of a problem as long as you have just one defined
(inline or in a separate file). If there are more schema files, the tns: in the generated soap file resolved mostly to the parent wsdl file,
which was obviously wrong.
node-soap now handles namespace prefixes which shouldn't be resolved (because it's not necessary) as so called ignoredNamespaces
which default to an Array of 3 Strings (). If this is not sufficient for your purpose you can easily add more namespace prefixes to this Array, or override it in its entirety
by passing an
ignoredNamespaces object within the options you pass in soap.createClient() method. A simple
ignoredNamespaces object, which only adds certain namespaces could look like this:
`
var options = {
ignoredNamespaces: {
namespaces: ['namespaceToIgnore', 'someOtherNamespace']
}
}
This would extend the of the WSDL processor to ['tns', 'targetNamespace', 'typedNamespace', 'namespaceToIgnore', 'someOtherNamespace']. If you want to override the default ignored namespaces you would simply pass the following
ignoredNamespaces object within the options:
`
var options = {
ignoredNamespaces: {
namespaces: ['namespaceToIgnore', 'someOtherNamespace'],
override: true
}
}
This would override the default of the WSDL processor to ['namespaceToIgnore', 'someOtherNamespace']`. (This shouldn't be necessary, anyways). * Author: Vinay Pulim
* Lead Maintainer: Joe Spencer
* All Contributors
[downloads-image]: http://img.shields.io/npm/dm/soap.svg
[npm-url]: https://npmjs.org/package/soap
[npm-image]: http://img.shields.io/npm/v/soap.svg
[travis-url]: https://travis-ci.org/vpulim/node-soap
[travis-image]: http://img.shields.io/travis/vpulim/node-soap.svg