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