Authentication

Every call needs a token. The authentication server issues it.

Flow

sequenceDiagram
    participant C as Client
    participant A as Auth Server
    C->>A: GET /GetPublicKey/
    A-->>C: PublicKey (Base64)
    Note over C: Convert username + password to UTF-16LE
    Note over C: Encrypt with PublicKey + Base64-encode
    C->>A: POST /GetSessionToken/ (JSON)
    A-->>C: Session Token
    Note over C: Use the token for all further requests

1. Fetch the PublicKey

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

The response contains the public key in the result[0] field.

2. Prepare the credentials

• Convert username and password to UTF-16 little endian without BOM
• Encrypt both with the PublicKey using OpenSSL
• Base64-encode the result

3. Build and send the JSON

{
  "User": "BASE64_ENCRYPTED_USERNAME",
  "Password": "BASE64_ENCRYPTED_PASSWORD",
  "PublicKey": "PUBLIC_KEY_FROM_STEP_1",
  "RememberMe": true
}

Parameters:

Field	Description
User	OpenSSL-encrypted and Base64-encoded username
Password	OpenSSL-encrypted and Base64-encoded password
PublicKey	From step 1
RememberMe	false = token valid for 12h; true = token valid for 90 days

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

Token in the WebKatalog

The token is passed as the URL parameter token:

{BASE}/planning?token={TOKEN}

• The WebKatalog remembers the token: in an iFrame in sessionStorage, otherwise in a cookie. Later calls without token keep using it.
• A new token resets the manufacturer and catalog position of the previous session.
• Without a token, the WebKatalog opens the login page; in an iFrame, in a new tab. An expired or invalid token is discarded and the login page then appears in the same window or iFrame.

For REST calls, the token is also appended as the token parameter.

Logging out

GET https://portal.3doffice.de/authsrv/AuthSrv.dll/datasnap/rest/AuthSrv/logout/{TOKEN}

---

PHP example

<?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];
}

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

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

HTTP POST to the sample implementation

The sample implementation (gettoken.php) expects a POST with:

Field	Description
username	Username
password	Password
rememberme	false = 12h, true = 90 days

The returned TOKEN is then used for all further calls.