soap-x509

A minimal node SOAP client with x509 signature security based off node-soap from Vinay Pulim v@pulim.com

A minimal node SOAP client with x509 signature security based off node-soap from Vinay Pulim v@pulim.com

This 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 (UsernameToken and PasswordText encoding is supported as well as x509 Signatures)

Install with npm:

  npm install soap-x509
  var soap = require('soap');
  var url = 'http://example.com/wsdl?wsdl';
  var args = {name: 'value'};
  soap.createClient(url, function(errclient) {
      client.MyFunction(args, function(errresult) {
          console.log(result);
      });
  });

wsdl is an xml string that defines the service.

  var myService = {
      MyService: {
          MyPort: {
              MyFunctionfunction(args) {
                  return {
                      name: args.name
                  };
              }
 
              // This is how to define an asynchronous function. 
              MyAsyncFunctionfunction(argscallback) {
                  // 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.

  server = soap.listen(...)
  server.log = function(typedata) {
    // type is 'received' or 'replied' 
  };

If server.authenticate is not defined no authentation 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');
  };

This is called prior to soap service method If the method is defined and returns false 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 reurns 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 WSSecurity('username', 'password'))
  client.MyFunction({name: 'value'}, function(errresult) {
      // result is a javascript object 
  })
  client.MyService.MyPort.MyFunction({name: 'value'}, function(errresult) {
      // 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:
  client.MyService.MyPort.MyFunction({name: 'value'}, function(errresult) {
      // result is a javascript object 
  }, {timeout: 5000})
  • soapHeader Object({rootName: {name: "value"}}) or strict xml-string
  • name Unknown parameter (it could just a empty string)
  • namespace prefix of xml namespace
  • xmlns URI

WSSecurity implements WS-Security. UsernameToken and PasswordText/PasswordDigest is supported. An instance of WSSecurity is passed to Client.setSecurity.

  new WSSecurity(username, password, passwordType)
    //'PasswordDigest' or 'PasswordText' default is PasswordText 

For x509 signed SOAP requests use WSSecurityCert

  new WSSecurityCert(privatePEM, publicP12PEM, password, encoding);