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.