Zum Hauptinhalt springen

SET Erzeugung

Empfangende Systeme melden dem Zustelldienst mit einem Security Event Token (SET), dass sie eine Einreichung erhalten haben und sie technisch verarbeiten können. Ebenso melden Empfänger dem Zustelldienst, wenn sie eine Einreichung technisch nicht verarbeiten können (mit einem entsprechenden SET). Im Folgenden ist das Erzeugen von SETs beschreiben.

Hinweis

Wenn Sie die FIT-Connect SDKs verwenden, dann können Sie sich auf den Aufruf der Schnittstelle zum SDK konzentrieren, weil die FIT-Connect SDKs viele Details automatisch intern umsetzen, wie auch das Erzeugen von SETs. Sie finden eine Beschreibung der SDKs im Hauptmenü unter SDKs.

Ereignis Payload​

Je nach SET ist ein Ereignis-Payload für das darin vorkommende Ereignis vorgesehen. Auf der Seite Ereignisse finden Sie eine Liste der Ereignisse und deren Struktur.

Verwendung von Authentication Tags in SET​

Die Ereignis-Payload als Teil des SETs wird zur Übermittlung von Ereignissen an den Zustelldienst, als signiertes JWT übergeben. Siehe hierzu das Post-Event der Submission API.

Die Ereignis-Payload setzt sich dabei aus dem Ereignis in URL-Format, möglichen Problems und den authenticationTags zusammen. Die authenticationTags sind der letzte Teil der JWE-Compact-Serialisierung, die für die einzelnen Bestandteile einer Einreichung verwendet werden.

Meta- und Fachdaten, sowie die Attachments sind jeweils in diesem Format vorhanden. Die einzelnen Bestandteile dieser Serialisierung finden Sie unter folgender URL: https://datatracker.ietf.org/doc/html/rfc7516#section-7.1.

Um die authenticationTags für die einzelnen Bestandteile des Events anzugeben, muss man also aus den übermittelten Daten zu einer Submission, die authenticationTags herausziehen und entsprechend in das JSON vor der Konvertierung in ein SignedJWT einfügen.

Dieses SignedJWT wird dann an den Endpunkt im Zustelldienst übermittelt, um die Statusveränderung umzusetzen (akzeptieren von Submission). Für das Akzeptieren von Replies entfällt der Schritt mit dem SignedJWT. Hier werden die authenticationTags gleich in der Payload übergeben. Vergleichen Sie hierzu bitte auch die entsprechende Submission API-Dokumentation

Authentication Tags Ereignis Payload​

Die Struktur der Authentication Tags Ereignis Payload sieht wie folgt aus.

{
  "authenticationTags": {
    "metadata": "XFBoMYUZodetZdvTiFvSkQ",
    "data": "UCGiqJxhBI3IFVdPalHHvA",
    "attachments": {
      "0b799252-deb9-42b0-98d3-c50d24bbafe0": "rT99rwrBTbTI7IJM8fU3El",
      "25abf553-0e53-43b9-a14a-1581b32a9ee5": "i7226HEB7IchCxNuh7lCiu",
      "046a9fa5-bed6-494b-aab6-d41056c6db79": "d48LxeolRdtFF4nzQibeYO"
    }
  }
}

Diese können Sie zum Beispiel wie folgt aufbauen.

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch Aufrufe der SDK-Methoden AcceptSubmissionAsync() und RejectSubmissionAsync des SDK-Interfaces IReceivedSubmission automatisch mit abgedeckt:

Das Beispiel oben ruft an einer Einreichung (Submission), die es vom Zustelldienst erhalten hat, die Methode AcceptSubmissionAsync() auf, um die Einreichung zu akzeptieren. Die Methode erzeugt intern automatisch ein SET und sendet es an den Zustelldienst.

Einreichung akzeptieren​

Wenn Sie in Ihrem Programm die Methode AcceptSubmissionAsync() aufrufen, dann bestätigen Sie, dass Ihr Programm (das empfangende System) diese Einreichung nachweislich erhalten hat und technisch verarbeiten kann.

receivedSubmission.AcceptSubmissionAsync().Wait();

Einreichung zurückweisen​

Rufen Sie in Ihrem Programm die Methode RejectSubmissionAsync() aufrufen, dann bestätigen Sie, dass Ihr Programm (das empfangende System) diese Einreichung technisch nicht verarbeiten kann. Deshalb weisen Sie diese Einreichung zurück.

receivedSubmission.RejectSubmissionAsync(new Problems(Problems.ProblemTypeEnum.MissingData, "Fax Nummer fehlt")).Wait();

Dazu finden Sie auf der Seite Ereignisprotokoll - Überblick eine Beschreibung. Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Codebeispiele - examples von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".

Problems Ereignis Payload​

Die Struktur der Problems Ereignis Payload sieht wie folgt aus.

{
  "problems": [
    {
      "type": "https://schema.fitko.de/fit-connect/events/problems/authentication-tag-incorrect",
      "title": "Das Authentication Tag des Metadatensatzes ist ungültig",
      "detail": "Das Authentication Tag des Metadatensatzes stimmt nicht mit dem im Submit-Submission-Event angegebenen Wert überein.",
      "instance": "metadata"
    }
  ]
}

Diese können Sie zum Beispiel wie folgt aufbauen.

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch Aufrufe der SDK-Methoden AcceptSubmissionAsync() und RejectSubmissionAsync des SDK-Interfaces IReceivedSubmission automatisch mit abgedeckt (siehe oben).

Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Codebeispiele - examples von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".

SET Claimset/Payload​

Die SET Payload ist wie folgt aufgebaut. Die Elemente der obersten Ebene sind bei allen SETs vorhanden (Ausnahme $schema). Der Claim events enthält als Schlüssel das eigentliche Ereignis, das ggf. einen eigenen Ereignis Payload (hier: authenticationTags) enthält. Mehr zu der Ereignis spezifischen Payload finden Sie auf dieser Seite under Ereignis Payload und auf der Ereignisse Seite

Warnung

Für die SET Payload wird unter $schema ein Schema zur Validierung definiert. Entspricht ein SET Payload nicht dem definierten Schema wird es z.B. vom Zustelldienst und vom Empfänger zurückgewiesen.

info

Die aktuellste Version des SET-Payload-Schemas ist in unserer Dokumentation zu finden. Mit den aktuellen Schemata stellt auch der Zustelldienst seine SETs aus. Die Versionen werden mit Ankündigung deprecated und sollten nicht mehr verwendet werden.

{
  "$schema": "https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json",
  "jti": "8538165b-9ce3-4097-871d-5b9581a3b4d9",
  "iss": "40847c29-06aa-40e2-bf28-c29884c694c4",
  "iat": 1622796532,
  "sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
  "txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90",
  "events": {
    "https://schema.fitko.de/fit-connect/events/accept-submission": {
      "authenticationTags": {
        "metadata": "XFBoMYUZodetZdvTiFvSkQ",
        "data": "UCGiqJxhBI3IFVdPalHHvA",
        "attachments": {
          "0b799252-deb9-42b0-98d3-c50d24bbafe0": "rT99rwrBTbTI7IJM8fU3El",
          "25abf553-0e53-43b9-a14a-1581b32a9ee5": "i7226HEB7IchCxNuh7lCiu",
          "046a9fa5-bed6-494b-aab6-d41056c6db79": "d48LxeolRdtFF4nzQibeYO"
        }
      }
    }
  }
}

SET Header​

Der Header eines SETs enthält immer die gleichen drei Angaben.

{
  "typ": "secevent+jwt",
  "kid": "{keyId}",
  "alg": "PS512"
}

SET erzeugen und signieren​

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch Aufrufe der SDK-Methoden AcceptSubmissionAsync() und RejectSubmissionAsync des SDK-Interfaces IReceivedSubmission automatisch mit abgedeckt (siehe oben).

Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Codebeispiele - examples von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".