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.

4

---

## Nutzung

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

> _**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!

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:

```xml

curl -d \

"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]]

## Beispiel

```xml

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

77

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

78

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.

79

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“.

80

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

81

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

82

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

83

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

84

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

85

```

Wiki-Quellcode von SecurePostdata

Navigation