Die Abkürzung SOAP steht für das Simple Object Access Protocol. Die meisten aktuellen Programmiersprachen unterstützen SOAP. Zusätzlich dient eine von LiveConfig bereitgestellte WSDL-Datei (Web Service Description Language) zur automatischen Erkennung der zur Verfügung stehenden Funktionen und Datentypen, so dass oft eine nahtlose Integration in eigene Anwendungen möglich ist.

Die Kommunikation für den SOAP-Zugriff erfolgt in Form von XML-Nachrichten über ganz normale HTTP(S)-Verbindungen. Beispielsweise sieht der Aufruf der SOAP-Funktion TestSayHello so aus:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns1="urn:LiveConfig">
  <SOAP-ENV:Body>
    <ns1:TestSayHello>
      <ns1:auth>
        <ns1:login>admin</ns1:login>
        <ns1:timestamp>2009-12-22T19:20:59.000Z</ns1:timestamp>
        <ns1:token>7juGMfg7N/F1G4t+S7XW99nRidg=</ns1:token>
      </ns1:auth>
      <ns1:firstname>Manfred</ns1:firstname>
      <ns1:lastname>Mustermann</ns1:lastname>
    </ns1:TestSayHello>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Bei einem erfolgreichen Aufruf sieht die Antwort so aus:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <TestSayHelloResponse xmlns="urn:LiveConfig">
      <greeting>Hello, Manfred Mustermann</greeting>
    </TestSayHelloResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Tritt während der Verarbeitung einer Anfrage ein Fehler auf, wird eine SOAP-Exception erzeugt. Diese enthält eine aussagekräftige Fehlermeldung. Die Fehlermeldung für einen abgelaufenen (ungültigen) Zeitstempel sieht beispielsweise so aus:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Server</faultcode>
      <faultstring>Authentication timestamp too far in past or future</faultstring>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

8.1.1. Voraussetzungen

Die SOAP-Schnittstelle von LiveConfig ist über die URL /liveconfig/soap zu erreichen. Die SOAP-Aufrufe müssen im document/literal-Stil formuliert sein (nicht als RPC/encoded).

Zudem müssen Sie LiveConfig mit einer Standard- oder Business-Lizenz betreiben. Mit der Basic-Lizenz steht die SOAP-API nicht zur Verfügung.

Zur Authentifizierung von SOAP-Zugriffen ist ein spezielles Token erforderlich - eine Prüfsumme aus Uhrzeit, Funktionsnamen und einem eigenen SOAP-Passwort. Zu jedem Benutzer in LiveConfig kann neben dem normalen Passwort ein davon unabhängiges SOAP-Passwort hinterlegt werden (siehe auch Abschnitt 2.7, „ Passwort-Initialisierung “.

Alle SOAP-Funktionen erfordern die Übermittlung eines auth-Parameters, welcher den Benutzernamen, einen Zeitstempel und das SOAP-Token enthält. Das Token ist eine Base64-codierte HMAC-SHA1-Prüfsumme über den Begriff LiveConfig, den eigenen Benutzernamen, den aufzurufenden Funktionsnamen und den Zeitstempel; als Schlüssel wird das SOAP-Passwort verwendet.

Folgendes Beispiel demonstriert die Erzeugung des auth-Parameters in PHP 5:

$user = 'admin';         # Benutzername
$pass = 'PaSsWoRt';      # SOAP-Passwort
$func = 'TestSayHello';  # aufzurufende SOAP-Funktion

# Zeitstempel erzeugen; Beispiel: '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# Token erzeugen:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts,
                                 $pass,
                                 true
                                )
                      );

# auth-Parameter erzeugen:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token
             );

Der im auth-Parameter angegebene Zeitstempel darf nicht mehr als 15 Minuten von der aktuellen Serverzeit auf dem LiveConfig-Server abweichen - ansonsten erfolgt eine Fehlermeldung. Die Uhrzeit muss als UTC/GMT-Zeit angegeben werden.

Wiederverkäufer: Funktionen mit Kundenrechten ausführen

Wiederverkäufer (Reseller) können alle SOAP-Funktionen auch mit den Rechten eines beliebigen ihrer Kunden ausführen. Das ist beispielsweise dann sinnvoll, wenn einem Kunden weitere untergeordnete Kunden zugeordnet werden sollen.

Für diesen Fall wird vor Berechnung des Tokens noch die (codierte) Kundennummer angefügt, und das optionale Feld customer im auth-Parameter gesetzt.

Der Kunde, mit dessen Rechten eine Funktion ausgeführt werden soll, muss für die jeweilige Funktion auch berechtigt sein - unabhängig von dem für die SOAP-Authentifizierung verwendeten Benutzer.

Beispiel in PHP5 für Ausführung mit Kundenrechten:

$user = 'admin';         # Benutzername
$pass = 'PaSsWoRt';      # SOAP-Passwort
$func = 'TestSayHello';  # aufzurufende SOAP-Funktion
$cust = 'c9R4hQp.T-rF';  # codierte Kunden-ID

# Zeitstempel erzeugen; Beispiel: '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# Token erzeugen:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts . $cust,
                                 $pass,
                                 true
                                )
                      );

# auth-Parameter erzeugen:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token,
              'customer'  => $cust
             );

LiveConfig kann eine WSDL-Beschreibung mit allen für den jeweiligen Benutzer erlaubten Funktionen und den dazugehörigen Datentypen erzeugen. Hierfür werden an die SOAP-URL der Parameter ?wsdl sowie Benutzername und SOAP-Passwort angefügt. Eventuelle Sonderzeichen im Passwort müssen natürlich entsprechend URL-codiert werden.

Das folgende Beispiel zeigt die Erzeugung eines SOAP-Clients mit PHP5 anhand einer automatisch generierten WSDL-Datei:

$user = 'admin';         # Benutzername
$pass = 'PaSsWoRt';      # SOAP-Passwort

# WSDL-URL erzeugen:
$url = 'https://your.liveconfig.server:8443/liveconfig/soap'
      .'?wsdl'  # WSDL anfordern
      .'&l=' . urlencode($user)
      .'&p=' . urlencode($pass);

# SOAP-Client erzeugen:
$client = new SoapClient($url,
                         array('style' => SOAP_DOCUMENT,
                               'use'   => SOAP_LITERAL,
                              )
                        );

Derzeit wird das SOAP-Passwort für den WSDL-Abruf im Klartext an die WSDL-URL angefügt. Die Übertragung zum Server erfolgt über das HTTPS-Protokoll dennoch verschlüsselt, und im access_log von LiveConfig wird das Passwort ausgeblendet. In einer späteren Version von LiveConfig soll statt des Passworts auch ein Hash verwendet werden. Da jedoch in manchen Programmiersprachen (z.B. beim WebService-Wizzard von C#) die direkte Eingabe einer WSDL-URL erwartet wird, wäre eine manuelle Hash-Berechnung unzumutbar.

8.1.4. Programmbeispiele

Im Folgenden finden Sie für die gängigsten Programmiersprachen kleine Beispielprogramme, welche die Verwendung der SOAP-Schnittstelle demonstrieren.

PHP5 unterstützt SOAP nativ und benötigt (im Gegensatz zu PHP4) keine weiteren PEAR/PECL-Pakete. Einzige Bedingung ist, dass PHP mit der Option --enable-soap übersetzt wurde. Ob die SOAP-Unterstützung aktiviert ist erkennt man an der phpinfo()-Ausgabe:

Das folgende Beispielprogramm zeigt alle notwendigen Schritte zur Ausführung einer SOAP-Anfrage an LiveConfig:

<?php

  # Configuration parameters:
  $user = 'admin';
  $pass = 'PaSsWoRd';
  $url  = 'https://your.liveconfig.server:8443/liveconfig/soap';

  # Construct WSDL URL
  $wsdl_url = $url
             .'?wsdl'
             .'&l=' . urlencode($user)
             .'&p=' . urlencode($pass);

  # Create SOAP client
  $client = new SoapClient($wsdl_url,
                           array('style'    => SOAP_DOCUMENT,
                                 'use'      => SOAP_LITERAL,
                                )
                          );

  # Construct SOAP token:
  $ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";
  $token = base64_encode(hash_hmac('sha1',
                                   'LiveConfig' . $user . 'TestSayHello' . $ts,
                                   $pass,
                                   true
                                  )
                        );

  $auth = array('login'     => $user,
                'timestamp' => $ts,
                'token'     => $token);
  
  $params = array('auth'      => $auth,
                  'firstname' => 'John',
                  'lastname'  => 'Doe');

  try {
    $response = $client->TestSayHello($params);
  } catch (SoapFault $soapFault) {
    die("Error while calling Web Service: " . $soapFault->faultstring . "\n");
  }

  echo "Response: " . $response->greeting . "\n";

?>

Die bei Perl häufig für WebServices genutzte Bibliothek SOAP::Lite unterstützt leider nicht das document/literal-Format, welches sich inzwischen als De-Facto-Standard für WebServices durchgesetzt hat.

Statt dessen empfehlen wir das Paket SOAP::WSDL, welches sich ebenfalls via CPAN installieren lässt.

Das folgende Beispielprogramm zeigt alle notwendigen Schritte zur Ausführung einer SOAP-Anfrage an LiveConfig:

#!/usr/bin/perl -w -t

use strict;
use SOAP::WSDL;
use MIME::Base64;
use Digest::HMAC_SHA1;
use URI::Escape;

# Configuration parameters:
my $user = 'admin';
my $pass = 'PaSsWoRd';
my $url  = 'http://your.liveconfig.server/liveconfig/soap';

# Construct WSDL URL
my $wsdl_url = $url
              .'?wsdl'
              .'&l=' . uri_escape($user)
              .'&p=' . uri_escape($pass);

my $firstname = 'John';
my $lastname  = 'Doe';

# Create SOAP client
my $soap = SOAP::WSDL->new( wsdl => $wsdl_url);

# Construct SOAP token:
my ($sec,$min,$hour,$mday,$mon,$year)=gmtime(time);
my $ts = sprintf('%4d-%02d-%02dT%02d:%02d:%02d.000Z',
                 $year+1900, $mon+1, $mday, $hour, $min, $sec);
my $token = MIME::Base64::encode(
                Digest::HMAC_SHA1::hmac_sha1(
                    'LiveConfig' . $user . 'TestSayHello' . $ts,
                    $pass
                ),
                ''
            );

my %auth = ('login'     => $user,
            'timestamp' => $ts,
            'token'     => $token
           );

my %params = ('auth'      => \%auth,
              'firstname' => $firstname,
              'lastname'  => $lastname
             );

my $som = $soap->call('TestSayHello', TestSayHello => \%params);

if ($som->fault) {
  die "Error while calling Web Service: " . $som->faultstring . "\n";
}

print "Response: " . $som->result() . "\n";

In der nachfolgenden Referenz sind alle SOAP-Funktionen aufgeführt.

Funktion Beschreibung
TestSayHello Test-Funktion zur Prüfung der SOAP-API
LiveConfigVersion Versionsnummer des LiveConfig-Servers abfragen
ContactAdd Kontaktdaten anlegen
ContactEdit Kontaktdaten bearbeiten
ContactGet Kontaktdaten abrufen
CustomerAdd Kunden anlegen
CustomerEdit Kunden bearbeiten
CustomerGet Kundendaten auslesen
HostingPlanAdd Webhosting-Angebot anlegen
HostingPlanGet Webhosting-Angebot abrufen
HostingSubscriptionAdd Webhosting-Vertrag anlegen
HostingSubscriptionDelete Webhosting-Vertrag löschen
HostingSubscriptionGet Details zu einem Webhosting-Vertrag auslesen
HostingSubscriptionEdit Webhosting-Vertrag bearbeiten
HostingDomainAdd Domain für Webhosting anlegen
HostingSubdomainAdd Subdomain für Webhosting anlegen
HostingDatabaseAdd Hosting-Vertrag eine bestehende Datenbank hinzufügen
HostingDatabaseDelete Datenbank löschen
HostingMailboxAdd E-Mail-Postfach einrichten
HostingMailboxEdit E-Mail-Postfach bearbeiten
HostingCronAdd neuen Cron-Job erstellen
HostingPasswordUserAdd neuen Benutzer für Verzeichnis-Passwortschutz anlegen
HostingPasswordPathAdd Verzeichnispfad mit Passwort schützen
HostingFtpAdd zusätzlichen FTP-Account anlegen
HostingLookup Hostingvertrag/Kunde suchen
UserAdd Benutzer anlegen
UserGet Benutzerdaten abrufen
UserEdit Benutzer bearbeiten
SessionCheck Session-ID prüfen
SessionCreate Session erzeugen (für Single-Sign-On)