Quick Start Guide with SOAP Part Two

 call CreateObject("SOAP.Lite") _
   .server("SOAP::Transport::HTTP::Daemon", _
     "LocalPort", 80) _
   .dispatch_to("/home/soaplite/modules") _
   .handle

 <%
    Response.ContentType = "text/xml"
    Response.Write(Server.CreateObject("SOAP.Lite") _
      .server("SOAP::Server") _ 
      .dispatch_to("/home/soaplite/modules") _
      .handle(Request.BinaryRead(Request.TotalBytes)) _
    )
  %>

 Alias /mod_perl/ "/Apache/mod_perl/"
  <Location /mod_perl>
    SetHandler perl-script
    PerlHandler Apache::Registry
    PerlSendHeader On
    Options +ExecCGI
  </Location>

 #!perl -w

  use SOAP::Transport::HTTP;
  
  SOAP::Transport::HTTP::CGI
    -> dispatch_to('/home/soaplite/modules')
    -> handle
  ;

 package SOAP::Apache;

  use SOAP::Transport::HTTP;
  
  my $server = SOAP::Transport::HTTP::Apache
    -> dispatch_to('/home/soaplite/modules') 
	
  sub handler { $server->handler(@_) }

  1;

 <Location /soap>
    SetHandler perl-script
    PerlHandler SOAP::Apache
  </Location>

 # directory-based access
  <Location /mod_soap>
    SetHandler perl-script
    PerlHandler Apache::SOAP
    PerlSetVar dispatch_to "/home/soaplite/modules"
    PerlSetVar options "compress_threshold => 10000"
  </Location>

  # file-based access
  <FilesMatch "\.soap$">
    SetHandler perl-script
    PerlHandler Apache::SOAP
    PerlSetVar dispatch_to "/home/soaplite/modules"
    PerlSetVar options "compress_threshold => 10000"
  </FilesMatch>

 SetHandler perl-script
  PerlHandler Apache::SOAP
  PerlSetVar dispatch_to "/home/soaplite/modules"
  PerlSetVar options "compress_threshold => 10000"

 #!perl -w

  use SOAP::Lite;
  
  print SOAP::Lite
    -> service('http://www.xmethods.net/sd/StockQuoteService.wsdl')
    -> getQuote('MSFT');

 #!perl -w

  use SOAP::Lite;
  
 my $service = SOAP::Lite
    -> service('http://www.xmethods.net/sd/StockQuoteService.wsdl');

The service description doesn't need to be on the Internet; you can access it from your local drive also:

6.c. client

 #!perl -w

  use SOAP::Lite
    service => 'http://www.xmethods.net/sd/StockQuoteService.wsdl',
    # service => 'file:/your/local/path/StockQuoteService.wsdl',
    # service => 'file:./StockQuoteService.wsdl',
  ;

  print getQuote('MSFT'), "\n";

This code works similar to the previous example (in OO style), but loads the description and imports all the methods, so you can use the functional interface.

And finally, a couple of one-liners for those who like to do something short and simple (albeit useful and powerful):

6.d. client

 # The following command is split for readability
  perl "-MSOAP::Lite service=>'http://www.xmethods.net/sd/StockQuoteService.wsdl'" 
       -le "print getQuote('MSFT')"

  perl "-MSOAP::Lite service=>'file:./quote.wsdl'" -le "print getQuote('MSFT')"

The last example (marked line) seems to be the shortest SOAP method invocation.

Security (SSL, basic/digest authentication, cookie-based authentication, ticket-based authentication, access control)

Though SOAP doesn't impose any security mechanisms (unless you count the SOAP Security Extensions: Digital Signature specification), the extensibility of the protocol allows you to leverage many security methods that are available for different protocols, like SSL over HTTP or S/MIME. We'll consider how SOAP can be used together with SSL, basic authentication, cookie-based authorization and access control.

SSL

Let's start with SSL. Surprisingly there is nothing SOAP-specific you need to do on the server side, and there is only a minor modification on the client side: just specify https: instead of http: as the protocol for your endpoint and everything else will be done for you. Obviously, both endpoints should support this functionality and the server should be properly configured.

7.a. client

 #!perl -w
  
  use SOAP::Lite +autodispatch => 
    uri => 'http://www.soaplite.com/My/Examples',

    proxy => 'https://localhost/cgi-bin/soap.cgi',

    on_fault => sub { my($soap, $res) = @_; 
      die ref $res ? $res->faultdetail : $soap->transport->status, "\n";
    }
  ;

  print getStateName(21);

Basic authentication

The situation gets even more interesting with authentication. Consider this code that accesses an endpoint that requires authentication.

7.b. client

 #!perl -w

  use SOAP::Lite +autodispatch => 
    uri => 'http://www.soaplite.com/My/Examples', 
    proxy => 'http://services.soaplite.com/auth/examples.cgi', 
    on_fault => sub { my($soap, $res) = @_; 
      die ref $res ? $res->faultdetail : $soap->transport->status, "\n";
    }
  ;

  print getStateName(21);

Keep in mind that the password will be in clear text during the transfer (not exactly in clear text; it will be base64 encoded, but that's almost the same) unless the user uses https (i.e. authentication doesn't mean encryption).

The server configuration for an Apache Web server with authentication can be specified in a .conf or in .htaccess file, and may look like this:

7.b. server (.htaccess)

 AuthUserFile /path/to/users/file/created/with/htpasswd
  AuthType Basic
  AuthName "SOAP::Lite authentication tests"
  require valid-user

If you run example 7.b against this endpoint, you'll probably get the following error:

7.b. result

 401 Authorization Required

You may provide the required credentials on the client side (user soaplite, and password authtest) overriding the function get_basic_credentials() in the class SOAP::Transport::HTTP::Client:

7.c. client

 #!perl -w
  
  use SOAP::Lite +autodispatch => 
    uri => 'http://www.soaplite.com/My/Examples', 
    proxy => 'http://services.soaplite.com/auth/examples.cgi', 
    on_fault => sub { my($soap, $res) = @_; 
      die ref $res ? $res->faultdetail : $soap->transport->status, "\n";
    }
  ;

  sub SOAP::Transport::HTTP::Client::get_basic_credentials { 
    return 'soaplite' => 'authtest';
  }

  print getStateName(21);

That gives you the correct result:

7.c. result

Massachusetts

Alternatively you may provide this information with a credentials() functions, but you need to specify the host and realm also:

7.d. client

 #!perl -w

  use SOAP::Lite +autodispatch => 
    uri => 'http://www.soaplite.com/My/Examples',

    proxy => [
      'http://services.soaplite.com/auth/examples.cgi', 
      credentials => [
        'services.soaplite.com:80',        # host:port
        'SOAP::Lite authentication tests', # realm
        'soaplite' => 'authtest',          # user, password
      ]
    ],

    on_fault => sub { my($soap, $res) = @_; 
      die ref $res ? $res->faultdetail : $soap->transport->status, "\n";
    }
  ;

  print SOAP->getStateName(21);

Under modern Perl you may get a warning about ``deprecated usage of inherited AUTOLOAD''. To avoid it use the full syntax: SOAP->getStateName(21) instead of getStateName(21).

The simplest and most convenient way would probably be to provide the user and password embedded in a URL. Surprisingly, this works:

7.e. client

 #!perl -w

  use SOAP::Lite;

  print SOAP::Lite
    -> uri('http://www.soaplite.com/My/Examples')

    -> proxy('http://soaplite:authtest@services.soaplite.com/auth/examples.cgi')

    -> getStateName(21)
    -> result;

Cookie-based authentication

Cookie-based authentication also doesn't require much work on the client side. Usually, it means that you need to provide credentials in some way, and if everything is OK, the server will return a cookie on success, and will then check it for all subsequent requests. Using available functionality you may not only support this behavior on the client side in one session, but even store cookies in a file and use the same server session for several runs. All you need to do is:

7.f. client

 #!perl -w

  use SOAP::Lite; 
  use HTTP::Cookies;

  my $soap = SOAP::Lite
    -> uri('urn:xmethodsInterop')

    -> proxy('http://services.xmethods.net/soap/servlet/rpcrouter', 
             cookie_jar => HTTP::Cookies->new(ignore_discard => 1));

  print $soap->echoString('Hello')->result;

All the magic is in the cookie jar. You may even add or delete cookies between calls, but the underlying module does everything you need by default. Add the option file => 'filename' to the call to new() to save and restore cookies between sessions. Not much work, huh? Kudos to Gisle Aas on that!

Ticket-based authentication

Ticket-based authentication is a bit more complex. The logic is similar to cookie-based authentication, but it is executed at the application level, instead of at the transport level. The advantage is that it works for any SOAP transport (not only for HTTP) and gives you a bit more flexibility. As a result, you won't get support from the Web server and you'll have to do everything manually. No big deal, right?

The first step is the ticket generation. We'll build a ticket that contains an e-mail address, a time and a signature.

7.g. server (TicketAuth)

 package TicketAuth;

  # we will need to manage Header information to get a ticket
  @TicketAuth::ISA = qw(SOAP::Server::Parameters);

  # ----------------------------------------------------------------------
  # private functions
  # ----------------------------------------------------------------------

  use Digest::MD5 qw(md5);

  my $calculateAuthInfo = sub {
    return md5(join '', 'something unique for your implementation', @_);
  };

  my $checkAuthInfo = sub {
    my $authInfo = shift;
    my $signature = $calculateAuthInfo->(@{$authInfo}{qw(email time)});
    die "Authentication information is not valid\n" 
      if $signature ne $authInfo->{signature};
    die "Authentication information is expired\n" 
      if time() > $authInfo->{time};
    return $authInfo->{email};
  };

  my $makeAuthInfo = sub {
    my $email = shift;
    my $time = time()+20*60; # signature will be valid for 20 minutes
    my $signature = $calculateAuthInfo->($email, $time);
    return +{time => $time, email => $email, signature => $signature};
  };

  # ----------------------------------------------------------------------
  # public functions
  # ----------------------------------------------------------------------

  sub login { 
    my $self = shift;

    pop; # last parameter is envelope, don't count it
    die "Wrong parameter(s): login(email, password)\n" unless @_ == 2;
    my($email, $password) = @_;

    # check credentials, write your own is_valid() function
    die "Credentials are wrong\n" unless is_valid($email, $password);

    # create and return ticket if everything is ok
    return $makeAuthInfo->($email);

  }

  sub protected { 
    my $self = shift;

    # authInfo is passed inside the header
    my $email = $checkAuthInfo->(pop->valueof('//authInfo'));

    # do something, user is already authenticated 
    return;
  }

It would be very careless (and insecure) to create calculateAuthInfo() as a normal, exposed function, because a client could invoke it directly and generate a valid ticket without providing valid credentials (unless you forbid it in the SOAP server configuration, but we'll show another way). Therefore, we create calculateAuthInfo(), checkAuthInfo() and makeAuthInfo() as 'private' functions, so only other functions inside the same file can access it. It effectively prevents clients from accessing them directly.

The login() function returns a hash that has an e-mail and time inside, as well as an MD5 signature that prevents the user from altering this information. Since the server used a secret string during signature generation, the user is not able to tamper with the resulting signature. To access protected methods, the client has to provide the obtained ticket in the header:

7.g. fragment

 # login
  my $authInfo = login(email => 'password');

  # convert it into the Header
  $authInfo = SOAP::Header->name(authInfo => $authInfo);

  # invoke protected method
  protected($authInfo, 'parameters');

This is just a fragment, but it should give you some ideas on how to implement ticket-based authentication on application level. You could even get the ticket in one place (via HTTP for example) and access a SOAP server via SMTP providing this ticket (ideally you should use PKI [public key infrastructure] for that matter).

Access control

Why would you need access control? Imagine you have a class and want to give access to it selectively; for example, read access to one person and read/write access to another person or a list of people. At a low level, read and write access means access to specific functions/methods in class.

You could put this check in at the application level (for example with ticket-based authentication), or you could split your class into two different classes and give one person access only to one of them. Neither of these is optimal solutions. We consider a different approach, where you create two different endpoints that refer to the same class on the server side, but have different access options.

7.e. server (first endpoint)

 use SOAP::Transport::HTTP;
  
  use Protected;
  SOAP::Transport::HTTP::CGI
    -> dispatch_to('Protected::readonly')
    -> handle
  ;

This endpoint will have access only to readonly() method in Protected class.

7.e. server (second endpoint)

 use SOAP::Transport::HTTP;

  use Protected;
  SOAP::Transport::HTTP::CGI
    -> dispatch_to('Protected')
    -> handle
  ;

This endpoint will have unrestricted access to all methods/functions in Protected class. Now you can put it under basic, digest or some other kind of authentication to prevent unauthorized access.

Thus, by combining the capabilities of a Web server with the SOAP server you can create an application that best suites your needs.

Handling LoLs (List of Lists, Structs, Objects, or something else)

Processing complex data structures isn't different in any aspect from the usual processing in your programming language. The general rule is simple: 'Treat the result of a SOAP call as a variable of specified type'.

The next example shows a service that works with array of structs:

8.a. client

 #!perl -w

  use SOAP::Lite;

  my $result = SOAP::Lite
        -> uri('urn:xmethodsServicesManager')
        -> proxy('http://www.xmethods.net/soap/servlet/rpcrouter')
        -> getAllSOAPServices();

  if ($result->fault) {
    print $result->faultcode, " ", $result->faultstring, "\n";
  } else {
    # reference to array of structs is returned
    my @listings = @{$result->result};

    # @listings is the array of structs
    foreach my $listing (@listings) {
      print "-----------------------------------------\n";
      # print description for every listing
      foreach my $key (keys %{$listing}) {
        print $key, ": ", $listing->{$key} || '', "\n";
      }        
    }
  }

The same is true about structs inside other structs, lists of objects, objects that have lists inside, etc. 'What you return on server side is what you get on client side, and let me know if you get something else.'

(OK, not always. You MAY get a blessed array even when you return a simple array on the other side and you MAY get a blessed hash when you return a simple one, but it won't change anything in your code, just access it as you usually do).

Major contributors:

Nathan Torkington

Basically started this work and pushed the whole process.

Tony Hong

Invaluable comments, fixes and input help me keep this material correct, fresh and simple.