Wiki-Quellcode von SecurePostdata
Zuletzt geändert von Form-Solutions GmbH am 25.01.2024
Zeige letzte Bearbeiter
| author | version | line-number | content |
|---|---|---|---|
| 1 | ## Allgemeines | ||
| 2 | |||
| 3 | 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. | ||
| 4 | |||
| 5 | --- | ||
| 6 | |||
| 7 | ## Nutzung | ||
| 8 | |||
| 9 | Um die Schnittstelle nutzen zu können, muss mittels eines serverseitiger POST-Aufrufs an eine URL mit folgender Syntax erfolgen: | ||
| 10 | |||
| 11 | <Server-Url>/metaform/Form-Solutions/securePostdata | ||
| 12 | |||
| 13 | Als Übertragungsformat wird `application/x-www-form-urlencoded`verwendet. Das Vertrauens-Niveau wird als `FS_STORK`-Parameter übergeben. | ||
| 14 | |||
| 15 | | FS-Vertrauens-Niveau | Wert | | ||
| 16 | | ------------------------------------ | ---------------------------- | | ||
| 17 | | Undefiniert | NONE | | ||
| 18 | | Niveau 1 (Benutzername und Kennwort) | L1 | | ||
| 19 | | Niveau 2 (nicht in Gebrauch) | L2 | | ||
| 20 | | Niveau 3 (Elster) | L3 | | ||
| 21 | | Niveau 4 (eID) | L4 (für eID authentifiziert) | | ||
| 22 | |||
| 23 | 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). | ||
| 24 | |||
| 25 | > **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](https://wiki.form-solutions.de/wiki/docwiki/view/Main/07_Einstellungen-Fachadministration/04_Server-Administration/) eingesehen werden. | ||
| 26 | |||
| 27 | 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.: | ||
| 28 | |||
| 29 | Antragsteller.Daten.AS_Name1.AS_Name1.AS_Name=Mustermann|FS_STORK=L1 | ||
| 30 | |||
| 31 | > _**Achtung:**_ | ||
| 32 | > | ||
| 33 | > Bei der alphabethischen Sortierung sind Parameter-Paare, deren ersten Buchstabe ein Großbuchstabe darstellt vor die Parameter-Paare zu sortieren, die mit Kleinbuchstaben beginnen! | ||
| 34 | |||
| 35 | 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: | ||
| 36 | |||
| 37 | ```xml | ||
| 38 | SecretKeySpec keySpec = new SecretKeySpec(password.getBytes(StandardCharsets.UTF_8), | ||
| 39 | "HmacSHA256"); | ||
| 40 | Mac mac = Mac.getInstance("HmacSHA256"); | ||
| 41 | mac.init(keySpec); | ||
| 42 | byte[] rawHmac = mac.doFinal(hashObject.getBytes(StandardCharsets.UTF_8)); | ||
| 43 | return DatatypeConverter.printHexBinary(rawHmac).toLowerCase(); | ||
| 44 | ``` | ||
| 45 | |||
| 46 | `hashObject` entspricht hierbei dem String, welcher verschlüsselt wird. | ||
| 47 | |||
| 48 | Somit ergibt sich bei einem API-Key `1234567890` folgender Beispielaufruf: | ||
| 49 | |||
| 50 | ```xml | ||
| 51 | curl -d \ | ||
| 52 | "Antragsteller.Daten.AS_Name1.AS_Name1.AS_Name=Mustermann&FS_STORK=L1&FS_HASH=\ | ||
| 53 | 3854e45b384302103b23786793bd6e11837a97fc741bc6e3fdee82b0bb723362" \ | ||
| 54 | -i -X POST https://demo.form-solutions.de/metaform/Form-Solutions/securePostdata | ||
| 55 | ``` | ||
| 56 | |||
| 57 | 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. | ||
| 58 | |||
| 59 | Im Fehlerfall können folgende Rückgabewerte resultieren: | ||
| 60 | |||
| 61 | | Fehlercode | Fehlernachricht | | ||
| 62 | | ---------------- | --------------------------------------- | | ||
| 63 | | Bad Request: 400 | missing hash code | | ||
| 64 | | Bad Request: 400 | invalid hash code | | ||
| 65 | | Bad Request: 400 | missing STORK level | | ||
| 66 | | Bad Request: 400 | invalid STORK level | | ||
| 67 | | Bad Request: 400 | invalid URL for 'unauthorized' redirect | | ||
| 68 | |||
| 69 | 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. | ||
| 70 | |||
| 71 | ![[Abbildung|@SecurePostData.jpg]] |