Der Authentifizierungs- und Autorisierungs-Server des Schallöhr-Verlags-Portals ist erreichbar unter der URL:

https://server.schalloehr-verlag.de/svuseraccount/command/execute 

Dabei ist die Verwendung des gesicherten Ports: 443 und die Verwendung des SSL-Protokolls obligatorisch und wird vom jeweiligen Server des Schallöhr-Verlagsportals durch eine dauerhafte Umleitung erzwungen.

Die Server mit den Rechenkernen des Schallöhr-Verlags sind zu erreichen unter der URL:

https://server.schalloehr-verlag.de/svcalculationengine/api/execute

Dabei ist die Verwendung des gesicherten Ports: 443 und die Verwendung des SSL-Protokolls obligatorisch und wird vom jeweiligen Server des Schallöhr-Verlagsportals durch eine dauerhafte Umleitung erzwungen.

Für gewisse Verträge und Berechnungsarten kann diese URL von der oben genannten abweichen. In diesem Fall wird ihnen die für sie gültige URL mit den Vertrags-Unterlagen im Informationsmaterial zugesandt, oder sie ist den Informationen aus der API-Verwaltungsapplikation im Kunden-Portal zu entnehmen.

Diese URLs werden in ähnlicher Weise verwendet, die für alle Anfragen an die Server des Schallöhr-Verlags-Portals gilt. Durch eine inadäquate Anfrage, beispielsweise durch einfache Eingabe der URL in die Adresszeile eines Webbrowsers, erzeugen sie einen parameterlosen Http-GET-Request, der von den Servern zurückgewiesen wird.

Anfrage:

Request URL: https://server.schalloehr-verlag.de/svcalculationengine/api/execute
Request Method: GET
Status Code: 200 OK
Remote Address: 85.10.204.107:443
Referrer Policy: no-referrer-when-downgrade

Antwort:

HTTP/1.1 200 OK
Date: Fri, 07 Dec 2018 00:01:35 GMT
Server: Apache/2.4.18 (Ubuntu)
X-Application-Context: application:production
Access-Control-Allow-Headers: Content-Type, Access-Control-Allow-Origin, Access-Control-Allow-Credentials, Access-Control-Allow- 
Methods, Authorization, X-Requested-With
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 3600
Vary: Accept-Encoding
Content-Encoding: gzip
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/html;charset=utf-8

Die Antwort des Servers enthält eine JSON-codierte Fehlermeldung:

{
    "responsecode": 301,
    "status": "failed"
}

Eine korrekte, wohlgeformte Anfrage an einen Schallöhr-Verlag-Webservice sehen Sie am Beispiel eines Login-Befehls, der einen Sitzungsschlüssel für eine existierende Test-Lizenz einer Demo-API beantragt.

Beispiel Request-Header:

POST /svuseraccount/command/execute HTTP/1.1
Host: server.schalloehr-verlag.de
Connection: keep-alive
Content-Length: 180
Accept: text/plain; charset=utf-8
Origin: https://portal.schalloehr-verlag.de
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Ubuntu Chromium/70.0.3538.110 
Chrome/70.0.3538.110 Safari/537.36
Content-Type: text/plain; charset=UTF-8
Referer: https://<your-company-domain>/<example>.html
Accept-Encoding: gzip, deflate, br
Accept-Language: de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7

Die Referrer-Informationen sind hier durch Platzhalter ausgetauscht.

Die in JSON codierte Anfrage, hier ein Platzhalterkommando, welches vom Service erkannt wird ist mit einem gültigen Sitzungsschlüssel ausgestattet.

{ 
  "command" : "noop", 
  "target" : "svuseraccount", 
  "sessionKey" : "7ce80d22-8968-42a1-8a7f-2e1915e25c4f"
}

Eine typische Antwort darauf sieht wie folgt aus:

HTTP/1.1 200 OK
Date: Mon, 10 Dec 2018 12:00:53 GMT
Server: Apache/2.4.18 (Ubuntu)
Access-Control-Allow-Headers: Content-Type, Access-Control-Allow-Origin, Access-Control-Allow-Credentials, Access-Control-Allow- 
Methods, Authorization, X-Requested-With
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 3600
Vary: Accept-Encoding
Content-Encoding: gzip
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/html;charset=utf-8

Die Antwort enthält ein ebenso in JSON codiertes Ergebnis-Objekt:

{
    "responsecode": 0,
    "status": "ok"
}

Der grundsätzliche Ablauf einer Anfrage an der Web-API ist auf der hier abgebildeten Grafik schematisch dargestellt. Der für den Kunden entscheidende Schritt ist natürlich die Durchführung der Berechnung.¹⁾ Diese Anfrage muss aber mit einem gültigen Sitzungsschlüssel legitimiert werden. Somit ist dieser Sitzungsschlüssel vor der Anfrage vom Authentifizierungs- und Autorisierungsserver des Schallöhr-Verlags zu beziehen.

Grundsätzlich muss jede Anfrage an einen Service des Schallöhr-Verlages mit einem Sitzungsschlüssel autorisiert werden. Der Sitzungsschlüssel ist eine Zeichenkette²⁾, der auf dem Server für eine begrenzte Zeit³⁾ gespeichert wird und dafür sorgt, dass eine damit legitimierte Anfrage daraufhin beurteilt werden kann, vom wem diese kommt, welcher Vertrag ihr zugrunde liegt, ob sie demgemäß legitimiert ist und dass eine Nutzung einer möglicherweise vertraglich vereinbarten Quota zugerechnet wird.

Beispiel eines Sitzungsschlüssels:

7ce80d22-8968-42a1-8a7f-2e1915e25c4f	

Codierung im Anfrageobjekt

"sessionKey":"7ce80d22-8968-42a1-8a7f-2e1915e25c4f"

Die im nächsten Abschnitt beschriebene Anfrage zum Bezug eines Sitzungsschlüssel benötigt naturgemäß keinen gültigen Sitzungsschlüssel, sondern wird durch Lizenzname und Passwort autorisiert, die in den Parametern untergebracht werden.

Aus diesem Grund der dringende Hinweis:

Implementieren Sie in keinem Fall die Erzeugung eines Sitzungsschlüssels in dem Teil der Applikation, der dem Kunden sichtbar ist oder der z.B. auf dessen Browser geladen wird. Erzeugen sie Kurzzeit-Sitzungsschlüssel ausschließlich durch eine Server-Software, die auf einem von ihnen gehosteten Server untergebracht ist. Tragen sie Sorge, dafür, unberechtigte Anfrage selbst zu erkennen und zu vermeiden.

Gültige Werte für den Parameter target sind:

svuseraccount

oder

SVUserAccount

für die Autorisierung und Authentifizierung.

svcalculationengine

oder

SVCalculationEngine

für die Berechnungsanfragen an den Rechenkern.

Der Parameter parameter liefert die eigentlichen Berechnungsdaten im Falle einer Anfrage an den Rechenkern. Dabei handelt es sich um ein meist komplexes JSON-Objekt, dessen Inhalt in der detaillierten Dokumentation für die Berechnungsanfragen erläutert wird.

Beim Bezug eines Kurzzeit-Sitzungs-Schlüssels enthält das Parameter-Objekt Lizenzname und Passwort:

"parameter" : {
  "nameLicence" : <Ihr Lizenzname>,
  "customerDomain" : "svs",
  "passwd": <Ihr Passwort>
}

Ein Beispiel Befehlsobjekt zur Erzeugung eines Kurzzeit-Sitzungs-Schlüssels sieht z.B. wie folgt aus:

{ "command": "login", 
  "target": "svuseraccount",  
  "parameter": {    
    "nameLicence": "Licence-ApiDemoStandardUserBasic-395",    
    "customerDomain": "svs",    
    "passwd": "123123"  }
}

Eine erfolgreiche Anfrage nach einem Kurzzeit-Sitzungsschlüssels liefert beispielsweise:

{
    "responsecode": 0,
    "status": "ok",
    "result": {
        "sessionKey": "94c2834d-f7fb-43a5-9902-2a16c2960c81"
    }
}

Wie in der obigen Abbildung schematisch dargestellt, muss zum Anstoß der Berechnung ein Kurzzeit-Sitzungsschlüssel gezogen werden. Dazu sind die Übermittlung des Vertragsnamens und des derzeit gültigen Passworts nötig. Deshalb sollte der Kurzzeitschlüssel nicht von einer Applikation erfragt werden, die im Zugriffsbereich des Endkundenbereichs liegt. Sie als Kunde sollten dafür eine Applikation auf dem Webserver vorhalten, welche diesen login im Hintergrund durchführt und von diesem sicheren Ort aus weiter verteilt.

Wir nennen diese Webserver-Funktionalität Authentifizierungsserver. Sie kann auf unterschiedlichste Weise realisiert werden. Am einfachsten ist es wohl diese Funktion als PHP-Skript auf Ihrer Webseite selbst server-seitig zu implementieren.

Hier können Sie eigene Parameter auswerten, wie Analyse ihrer eigenen Zugriffsschemata, ihrer eigenen Autorisierung, die Kontrolle über die Menge an Zugriffen oder den Schutz vor DOS-Attacken.

1. Programmiersprache: JavaScript
2. Serverseitige Umgebung: NodeJS, zB. Version v9.11.2
3. Freischaltung Port: 4711, oder Änderung des Scripts.

In Folge sehen sie den JavaScript-Code eines Beispiel-Autorisierungsservers aufgelistet, der in den meisten Fällen unverändert funktionieren sollte, sofern sie die Platzhalter für Lizenz-Name und Passwort einfügen. Dann müssen Sie nur noch das Script an ihre URL-Landschaft anpassen und auf ihrem Webserver deployen.

Sie können diese Implementierung gerne als Grundlage verwenden und sie entsprechend anpassen und um ihre Authentifizierung und Autorisierung erweitern.

/**
 * Name der Api-Lizenz des Kunden
 */
var licencename="<Name der Kundenlizenz>";

/***
 * Aktuelles Portal-Passwort des Kunden
 */
var passwd="<Aktuelles Portalpasswort>";

/**
 * Basis URL des Schallöhr-Verlag Server, 
 * der die Rechner-APIs und das Autorisierungssystem bereitstellt.
 */
var host='server.schalloehr-verlag.de';

/**
 * Lokaler Port des Responderservers
 */
var responderport = 4711;


var https = require('https');

var http = require('http');

var token = {
        command:"login",
        target:"svuseraccount",
        parameter:{
            nameLicence:licencename,
            passwd:passwd,
            customerDomain:"svs"
        }
};

var options = {
    hostname: host,
    port: 443,
    path: '/svuseraccount/command/execute',
    method: 'POST',
    rejectUnauthorized: false,
    requestCert: true,
    headers: {
        'Content-Type': 'application/json',
    }
  };

function callbackSVAuthenticationService ( retrieveSessionKey, onError ) {
    var req = https.request(options, function(res) {
        res.setEncoding('utf8');
        res.on('data', function (encodedbody) {
                body=JSON.parse(encodedbody);
                if (body.status=="ok") {
                    retrieveSessionKey (body.result.sessionKey);
                } else {
                    onError( body.responsecode, body.message);
                }
            });
        req.on('error', function(e) {
              onError(-1, e.message);
            });      
        });
    req.write(JSON.stringify(token));
    req.end();
} 

http.createServer(function (req, res) {
  function success (sessionKey){
    console.log("Generated key: "+sessionKey);
    res.writeHead(200, {'Content-Type': 'text/plain'});
    res.write(sessionKey);
    res.end();  
  }
  function error(code, message){
    console.log("Error: "+code+" | "+message);
    res.writeHead(200, {'Content-Type': 'text/plain'});
    res.write("Code: "+code+" Message: "+message);
    res.end();  
  }
  callbackSVAuthenticationService( success, error );
}).listen( responderport );

Beachten sie bitte, dass diese Demo-Implementierung jeden Zugriff auf der Konsole loggt, was nur zum Ausprobieren sinnvoll ist. Ersetzen sie bitte alle sicherheitsrelevanten Funktionen durch ihre Wunsch-Implementierung.

Zur Durchführung der Berechnungsanfrage lesen sie bitte die ausführlichen, spezifischen Dokumentationen.

Im Folgenden finden sie die wichtigsten Fehlercodes für ihre Anfragen aufgelistet: