Vorbefüllung von Assistenten - SecurePostdata

Page / - zuletzt bearbeitet von Form-Solutions GmbH am 25.01.2024

SecurePostdata

zuletzt bearbeitet von Form-Solutions GmbH

am 25.01.2024

Inhaltsverzeichnis

Allgemeines

Nutzung

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-urlencodedverwendet. 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).

Achtung: 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

Achtung:
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.