SecurePostdata

Allgemeines

Um eine Vorab-Authentifizierung für einen Antragsassistenten durch ein Portal durchzuführen, müssen sowohl die Benutzer-/Antragstellerdaten, als auch das verifizierte Vertrauens-Niveau gesichert übergeben werden.

Nutzung

Um die Schnittstelle nutzen zu können, muss mittels eines serverseitiger POST-Aufrufs an eine URL mit folgender Syntax erfolgen:

<Server-Url>/metaform/Form-Solutions/securePostdata

Als Übertragungsformat wird application/x-www-form-urlencoded verwendet. Das Vertrauens-Niveau wird als FS_STORK-Parameter übergeben.

FS-Vertrauens-Niveau Wert

Undefiniert

NONE

Niveau 1 (Benutzername und Kennwort)

L1

Niveau 2 (nicht in Gebrauch)

L2

Niveau 3 (Elster)

L3

Niveau 4 (eID)

L4 (für eID authentifiziert)

Zur Absicherung kommt einerseits eine Basic-Authentifizierung zum Einsatz. Bei dem Benutzernamen handelt es sich dabei um die Mandantennummer, beim Kennwort um einen API-Key (ehemals CMS-Key).

Der zu benutzende API-Key muss seit dem Release 4.68.0 über das Recht "SecurePostData" oder "Unbegrenzt" verfügen.
Die Konfiguration der Berechtigungen an den API-Key’s können hier eingesehen werden.

Zum Anderen muss über alle Parameter inkl. FS_STORK ein Hash gebildet und als Parameter FS_HASH mit übergeben werden. Dazu sind alle Parameter-Paare alphabetisch zu sortieren und mittels | zu verknüpfen. Bsp.:

Antragsteller.Daten.AS_Name1.AS_Name1.AS_Name=Mustermann|FS_STORK=L1

Bei der alphabethischen Sortierung sind Parameter-Paare, deren ersten Buchstabe ein Großbuchstabe darstellt vor die Parameter-Paare zu sortieren, die mit Kleinbuchstaben beginnen!

Daraus wird ein Hmac-Hash in Base64-Kleinbuchstaben mit dem Hash-Algorithmus SHA-256 unter Verwendung des API-Keys als Kennwort generiert. Eine Beispielimplementierung in Java sieht wie folgt aus:

SecretKeySpec keySpec = new
SecretKeySpec(password.getBytes(StandardCharsets.UTF_8),
  "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(keySpec);
byte[] rawHmac =
mac.doFinal(hashObject.getBytes(StandardCharsets.UTF_8));
return DatatypeConverter.printHexBinary(rawHmac).toLowerCase();

hashObject entspricht hierbei dem String, welcher verschlüsselt wird.

Somit ergibt sich bei einem API-Key 1234567890 folgender Beispielaufruf:

curl -d \
  "Antragsteller.Daten.AS_Name1.AS_Name1.AS_Name=Mustermann&FS_STORK=L1&FS_HASH=\
  3854e45b384302103b23786793bd6e11837a97fc741bc6e3fdee82b0bb723362" \
  -i -X POST https://demo.form-solutions.de/metaform/Form-Solutions/securePostdata

Als Rückgabewert erhält wie bei der Vorbefüllung über die Postdata-Schnittstelle eine Cache-ID. Diese muss dann am eigentlichen Aufruf durch den Benutzer als Parameter cacheID angehängt werden.

Im Fehlerfall können folgende Rückgabewerte resultieren:

Fehlercode Fehlernachricht

Bad Request: 400

missing hash code

Bad Request: 400

invalid hash code

Bad Request: 400

missing STORK level

Bad Request: 400

invalid STORK level

Bad Request: 400

invalid URL for 'unauthorized' redirect

Sollte beim Start des Assistenten die Mindestanforderung des Vertrauens-Niveau nicht erfüllt sein, wird eine Fehlerseite ausgegeben. Alternativ lässt sich eine spezifische Fehlerseite per URL-Parameter unauthorizedUrl anhängen, auf welche weitergeleitet wird. Dieser Parameter muss, sofern gesetzt, ebenfalls mit in den Hash-Code einbezogen werden.

Abbildung

Beispiel

  1. Die gesammelten Vorbefüllungsdaten werden lexikographisch sortiert. Abhängig von Groß- vor Kleinbuchstaben erfolgt die Einsortierung.

  2. Die sortierten Wertepaare werden zu einem String der Form Feldname1=Feldwert1|Feldname2=Feldwert2|FS_STORK=Vertrauensniveau|ordnungsId={UUID}9 konkateniert.

  3. Aus dem resultierenden String wird ein Hmac-Hash in Base64-Kleinbuchstaben mit dem Hash-Algorithmus SHA-256 unter Verwendung des API-Keys des jeweiligen Mandanten als Kennwort generiert und als FS_HASH gespeichert.

  4. Alle Wertepaare – inklusive ordnungsId, FS_STORK, und FS_HASH, werden über einen serverseitigen POST-Aufruf an eine URL mit der Syntax <Server-Url>/metaform/Form-Solutions/securePostdata im Format application/x-www-form-urlencoded übertragen. Dabei werden Mandant und API-Key als Benutzername und Kennwort für eine Basic-Authentifizierung genutzt. Der verwendete API-Key verfügt über das Recht „Secure-Postdata“.

  5. Der Rückgabewert des Aufrufs wird als cacheID gespeichert.

  6. Der Nutzer wird an den eigentlichen Veröffentlichungslink des Formulars inklusive zusätzlichem URL-Parameter cacheID weitergeleitet.

  7. Der Nutzer füllt das Formular aus und klickt auf die Schaltfläche „Einreichen“.

  8. MACH formsolutions ruft den eingangs als notifyUrl übergebenen Endpunkt auf und übergibt die neu vergebene Transaktions-ID.

  9. Über die Submission-API lädt dieser Assistent die XML, PDF und etwaige Dateianhänge herunter.