Authentication

There are several ways of authenticating over SOAP, that a service might implement. This lists a few of the most common patterns.

HTTP Authentication

Support for HTTP-authentication depends on the http driver. They all support Basic authentication, but some drivers also support more exotic/advanced types. The best support is currently provided by curb.

HTTP-authentication can be employed by overriding on_after_create_http_request and setting credentials. The driver automatically picks the appropriate auth type to use, depending on the servers capabilities. Eg.:

class MyService < Handsoap::Service
  def on_after_create_http_request(http_request)
    http_request.set_auth @@username, @@password
  end

  @@username = ""
  def self.username=(username)
    @@username = username
  end

  @@password = ""
  def self.password=(password)
    @@password = password
  end
end

SSL

TODO

The HTTP layer currently doesn’t provide methods to use SSL certificates, but it’s on the TODO list. If you need this feature, you should open an issue in the issue tracker.

Unsupported protocol errors

If you are using curb and having trouble consuming a https-based SOAP service (“Unsupported protocol”), you may have compiled (lib)curl without SSL support. If you are using ports on Mac OS X, try:

$ sudo port install curl +ssl
$ sudo gem install curb

WS-Security

The WS-Security protocol requires certain elements to be added to the <Header/> element of the SOAP request. You can add these in the on_create_document hook, so they apply for all requests.

class MyService < Handsoap::Service
  def on_create_document(doc)
    doc.alias 's', "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
    header = doc.find("Header")
    header.add "s:Security" do |s|
      s.set_attr "env:mustUnderstand", "0"
      s.add "s:Username", @@username
    end
  end

  @@username = ""
  def self.username=(username)
    @@username = username
  end
end

Sessions and cookies

Some services requires cookie support for authentication. To enable this, you have to reuse the same http-client for all request on a service, and enable cookie support on it. Currently, only the curb driver supports this feature.

class MyService < Handsoap::Service
  def http_driver_instance
    unless @driver_instance
      @driver_instance = super
      @driver_instance.enable_cookies = true
    end
    @driver_instance
  end
end