Authentifizierung

Ein Token wird für alle API-Aufrufe benötigt. Er dient der Authentifizierung und kann über den Authentifizierungsserver generiert werden.

Ablauf

sequenceDiagram
    participant C as Client
    participant A as Auth Server
    C->>A: GET /GetPublicKey/
    A-->>C: PublicKey (Base64)
    Note over C: username + password in UTF-16LE konvertieren
    Note over C: Mit PublicKey verschlüsseln + Base64 kodieren
    C->>A: POST /GetSessionToken/ (JSON)
    A-->>C: Session Token
    Note over C: Token für alle weiteren Requests verwenden

Schritt für Schritt

1. PublicKey abrufen

GET https://portal.3doffice.de/authsrv/AuthSrv.dll/datasnap/rest/AuthSrv/GetPublicKey/

Die Antwort enthält den öffentlichen Schlüssel im result[0]-Feld.

2. Credentials vorbereiten

• username und password in UTF-16 Little Endian ohne BOM umwandeln
• Beide mit dem PublicKey über OpenSSL verschlüsseln
• Ergebnis Base64-kodieren

3. JSON erstellen und senden

{
  "User": "BASE64_VERSCHLUESSELTER_USERNAME",
  "Password": "BASE64_VERSCHLUESSELTES_PASSWORT",
  "PublicKey": "PUBLIC_KEY_AUS_SCHRITT_1",
  "RememberMe": true,
  "AppKey": "APPLICATION_KEY"
}

Parameter:

Feld	Beschreibung
User	OpenSSL-verschlüsselter und Base64-kodierter Benutzername
Password	OpenSSL-verschlüsseltes und Base64-kodiertes Passwort
PublicKey	Aus Schritt 1
RememberMe	false = Token 12h gültig; true = Token 90 Tage gültig
AppKey	Application Key (pro Anwendung vergeben)

POST https://portal.3doffice.de/authsrv/AuthSrv.dll/datasnap/rest/AuthSrv/%22GetSessionToken%22/

4. Token verwenden

Der zurückgegebene Token wird für alle weiteren Aufrufe als URL-Parameter token mitgegeben.

---

PHP-Beispiel

<?php
function encryptData($dataToEncrypt, $pubKey) {
  $sealed = "";
  $dataToEncrypt = iconv("UTF-8", "UCS-2LE", $dataToEncrypt);
  openssl_public_encrypt($dataToEncrypt, $sealed, $pubKey);
  return base64_encode($sealed);
}

function getToken($username, $pw, $rememberme) {
  $json   = file_get_contents('https://portal.3doffice.de/authsrv/AuthSrv.dll/datasnap/rest/AuthSrv/GetPublicKey/');
  $obj    = json_decode($json);
  $pubKey = $obj->result[0];

  $json_post_data = json_encode(array(
    'User' => encryptData($username, $pubKey),
    'Password' => encryptData($pw, $pubKey),
    'PublicKey' => $pubKey,
    'RememberMe' => $rememberme
  ));

  $options = array(
    'http' => array(
      'method'  => 'POST',
      'content' => $json_post_data,
      'header'  => "Content-Type: application/json\r\n" .
                   "Accept: application/json\r\n"
    )
  );

  $context = stream_context_create($options);
  $result = file_get_contents(
    'https://portal.3doffice.de/authsrv/AuthSrv.dll/datasnap/rest/AuthSrv/%22GetSessionToken%22/',
    false,
    $context
  );

  $response = json_decode($result);
  return $response->result[0];
}

// Verwendung:
$username   = $_POST["username"];
$pw         = $_POST["password"];
$rememberme = ($_POST["rememberme"] == "true");

echo(getToken($username, $pw, $rememberme));
?>

HTTP POST zur Beispielimplementierung

Die Beispielimplementierung (gettoken.php) erwartet einen POST mit:

Feld	Beschreibung
username	Benutzername
password	Passwort
rememberme	false = 12h, true = 90 Tage

Der zurückgegebene TOKEN wird dann für alle weiteren Aufrufe verwendet.