Security News
GitHub Removes Malicious Pull Requests Targeting Open Source Repositories
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
The 'soap' npm package is a SOAP client and server library for Node.js. It allows you to create SOAP clients to consume web services and also create SOAP servers to expose your own web services.
Create a SOAP Client
This feature allows you to create a SOAP client that can consume a SOAP web service. You provide the WSDL URL, and the client can then call the web service methods.
const soap = require('soap');
const url = 'http://example.com/wsdl?wsdl';
soap.createClient(url, function(err, client) {
if (err) throw err;
client.MyFunction({name: 'value'}, function(err, result) {
if (err) throw err;
console.log(result);
});
});
Create a SOAP Server
This feature allows you to create a SOAP server that exposes your own web service. You define the service and its methods, and provide the WSDL file.
const soap = require('soap');
const express = require('express');
const app = express();
const myService = {
MyService: {
MyPort: {
MyFunction: function(args) {
return { name: args.name };
}
}
}
};
const xml = require('fs').readFileSync('myservice.wsdl', 'utf8');
soap.listen(app, '/wsdl', myService, xml);
app.listen(8000);
Handle SOAP Headers
This feature allows you to add custom SOAP headers to your SOAP client requests. This can be useful for authentication or other custom header requirements.
const soap = require('soap');
const url = 'http://example.com/wsdl?wsdl';
soap.createClient(url, function(err, client) {
if (err) throw err;
const soapHeader = { 'MyHeader': 'value' };
client.addSoapHeader(soapHeader);
client.MyFunction({name: 'value'}, function(err, result) {
if (err) throw err;
console.log(result);
});
});
The 'strong-soap' package is another SOAP client and server library for Node.js. It is similar to 'soap' but offers additional features like better WSDL handling and support for more complex SOAP scenarios. It is maintained by the StrongLoop team.
The 'easy-soap-request' package is a lightweight SOAP client for Node.js. It focuses on simplicity and ease of use, making it a good choice for simple SOAP requests. However, it does not offer server-side capabilities like 'soap'.
The 'node-soap-client' package is a minimalistic SOAP client for Node.js. It is designed to be easy to use and integrates well with modern JavaScript features like Promises and async/await. It is a good alternative if you only need client-side functionality.
A SOAP client and server for node.js.
This module lets you connect to web services using SOAP. It also provides a server that allows you to run your own SOAP services.
Install with npm:
npm install soap
var soap = require('soap');
var url = 'http://example.com/wsdl?wsdl';
var args = {name: 'value'};
soap.createClient(url, function(err, client) {
client.MyFunction(args, function(err, result) {
console.log(result);
});
});
The options
argument allows you to customize the client with the following properties:
.wsdl
file.request(rurl, data, callback, exheaders, exoptions)
.wsdl is an xml string that defines the service.
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
})
},
// This is how to receive incoming headers
HeadersAwareFunction: function(args, cb, headers) {
return {
name: headers.Token
};
}
}
}
}
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.
server = soap.listen(...)
server.log = function(type, data) {
// type is 'received' or 'replied'
};
Server instances emit the following events:
function(request, methodName)
.function(headers, methodName)
.The sequence order of the calls is request
, headers
and then the dedicated
service method.
A service method can reply with a SOAP Fault to a client by throw
ing an
object with a Fault
property.
throw {
Fault: {
Code: {
Value: "soap:Sender",
Subcode: { value: "rpc:BadArguments" }
},
Reason: { Text: "Processing Error" }
}
};
To change the HTTP statusCode of the response include it on the fault. The statusCode property will not be put on the xml message.
throw {
Fault: {
Code: {
Value: "soap:Sender",
Subcode: { value: "rpc:BadArguments" }
},
Reason: { Text: "Processing Error" },
statusCode: 500
}
};
A service method can look at the SOAP headers by providing a 3rd arguments.
{
HeadersAwareFunction: function(args, cb, headers) {
return {
name: headers.Token
};
}
}
It is also possible to subscribe to the 'headers' event. The event is triggered before the service method is called, and only when the SOAP Headers are not empty.
server = soap.listen(...)
server.on('headers', function(headers, methodName) {
// It is possible to change the value of the headers
// before they are handed to the service method.
// It is also possible to throw a SOAP Fault
});
First parameter is the Headers object; second parameter is the name of the SOAP method that will called (in case you need to handle the headers differently based on the method).
If server.authenticate
is not defined then no authentication will take place.
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');
};
The server.authorizeConnection
method is called prior to the soap service method.
If the method is defined and returns false
then the incoming connection is
terminated.
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.
client.describe() // returns
{
MyService: {
MyPort: {
MyFunction: {
input: {
name: 'string'
}
}
}
}
}
node-soap
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 returns a string of XML.By default there are 3 protocols:
####BasicAuthSecurity
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) client.setSecurity(new soap.ClientSSLSecurity(
'/path/to/key'
, '/path/to/cert'
, {/*default request options*/}
));
####WSSecurity
client.setSecurity(new soap.WSSecurity('username', 'password'))
####BearerSecurity
client.setSecurity(new soap.BearerSecurity('token'));
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
})
client.MyService.MyPort.MyFunction({name: 'value'}, function(err, result) {
// result is a javascript object
})
###Overriding the namespace prefix
node-soap
is still working out some kinks regarding namespaces. If you find that an element is given the wrong namespace prefix in the request body, you can add the prefix to it's name in the containing object. I.E.:
client.MyService.MyPort.MyFunction({'ns1:name': 'value'}, function(err, result) {
// request body sent with `<ns1:name`, regardless of what the namespace should have been.
}, {timeout: 5000})
client.MyService.MyPort.MyFunction({name: 'value'}, function(err, result) {
// result is a javascript object
}, {timeout: 5000})
soapHeader
Object({rootName: {name: "value"}}) or strict xml-stringname
Unknown parameter (it could just a empty string)namespace
prefix of xml namespacexmlns
URIClient instances emit the following events:
WSSecurity implements WS-Security. UsernameToken and PasswordText/PasswordDigest is supported. An instance of WSSecurity is passed to Client.setSecurity.
new WSSecurity(username, password, options)
//the 'options' object is optional and contains properties:
//passwordType: 'PasswordDigest' or 'PasswordText' default is PasswordText
//hasTimeStamp: true or false default is true
Sometimes it is necessary to override the default behaviour of node-soap
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:
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:
var wsdlOptions = {
valueKey: 'theVal'
};
soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
// your code
});
###Overriding the xml
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 :
dom = {
$xml: '<parentnode type="type"><childnode></childnode></parentnode>'
};
<tns:dom>
<parentnode type="type">
<childnode></childnode>
</parentnode>
</tns:dom>
You can define your own xmlKey
by passing it in the wsdl_options
to the createClient call like so:
var wsdlOptions = {
xmlKey: 'theXml'
};
soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
// your code
});
###Overriding the attributes
key
You can achieve attributes like:
<parentnode>
<childnode name="childsname">
</childnode>
</parentnode>
By attaching an attributes object to a node.
{
parentnode: {
childnode: {
attributes: {
name: 'childsname'
}
}
}
}
However, "attributes" may be a reserved key for some systems that actually want a node
<attributes>
</attributes>
In this case you can configure the attributes key in the wsdlOptions
like so.
var wsdlOptions = {
attributesKey: '$attributes'
};
soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
client.*method*({
parentnode: {
childnode: {
$attributes: {
name: 'childsname'
}
}
}
});
});
If an Element in a schema
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 schema
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 (['tns', 'targetNamespace', 'typedNamespace']
).
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 ignoredNamespaces
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 ignoredNamespaces
of the WSDL
processor to ['namespaceToIgnore', 'someOtherNamespace']
. (This shouldn't be necessary, anyways).
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 ignoredNamespaces
of the WSDL
processor to ['namespaceToIgnore', 'someOtherNamespace']
. (This shouldn't be necessary, anyways).
If an Element in a schema
definition depends has a basenamespace defined but the request does not need that value, for example you have a "sentJob" with basenamespace "v20"
but the request need only: set in the tree structure, you need to set the ignoreBaseNameSpaces to true. This is set because in a lot of workaround the wsdl structure is not correctly
set or the webservice bring errors.
By default the attribute is set to true. An example to use:
A simple ignoredNamespaces
object, which only adds certain namespaces could look like this:
var options = {
ignoredNamespaces: true
}
Unit testing services that use soap clients can be very cumbersome. In order to get
around this you can use soap-stub
in conjunction with sinon
to stub soap with
your clients.
// test-initialization-script.js
var sinon = require('sinon');
var soapStub = require('soap/soap-stub');
var urlMyApplicationWillUseWithCreateClient = 'http://path-to-my-wsdl';
var clientStub = {
SomeOperation: sinon.stub()
};
clientStub.SomeOperation.respondWithError = soapStub.createRespondingStub({..error json...});
clientStub.SomeOperation.respondWithSuccess = soapStub.createRespondingStub({..success json...});
soapStub.registerClient('my client alias', urlMyApplicationWillUseWithCreateClient, clientStub);
// test.js
var soapStub = require('soap/soap-stub');
describe('myService', function() {
var clientStub;
var myService;
beforeEach(function() {
clientStub = soapStub.getStub('my client alias');
soapStub.reset();
myService.init(clientStub);
});
describe('failures', function() {
beforeEach(function() {
clientStub.SomeOperation.respondWithError();
});
it('should handle error responses', function() {
myService.somethingThatCallsSomeOperation(function(err, response) {
// handle the error response.
});
});
});
});
FAQs
A minimal node SOAP client
The npm package soap receives a total of 0 weekly downloads. As such, soap popularity was classified as not popular.
We found that soap demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.