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 ein SDK der FITKO verwenden, dann können Sie sich auf den Aufruf der Schnittstelle zum SDK konzentrieren, weil die SDKs der FITKO 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.

Warnung

Derzeit ist es möglich, Ereignisse auch ohne Ereignis-Payload zu senden. In diesem Fall darf kein SET-Payload-Schema (unter $schema) angegeben werden. Denn sollte ein SET-Payload-Schema verwendet werden, das ein Ereignis-Payload vorschreibt, wird das SET ohne diese Ereignis-Payload vom Zustelldienst mit einem Fehler zurückgewiesen.

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:

receivedSubmission.AcceptSubmissionAsync();

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.
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. 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 der FITKO 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 der FITKO 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. Es ist aktuell noch möglich, kein $schema anzugeben. Dadurch findet keine Validierung aufseiten des Zustelldienstes und des Empfängers statt. Dies wird in unspezifizierter Zukunft deprecated und alle SETs müssen dann ein valides Schema verwenden und angeben.

Derzeit ist es auch noch möglich, Ereignisse auch ohne Ereignis Payload zu senden. In diesem Fall darf kein SET-Payload-Schema (unter $schema) angegeben werden. Denn sollte ein SET-Payload-Schema verwendet werden, das ein Ereignis-Payload vorschreibt, wird das SET ohne diese Ereignis-Payload vom Zustelldienst mit einem Fehler zurückgewiesen.

info

Derzeit ist die Version 1.0.0 des SET-Payload-Schemas aktuell. Mit diesem Schema 1.0.0 stellt auch der Zustelldienst seine SETs aus. Bis auf weiteres kann auch noch die Version 0.1.0 verwendet werden. Inhaltlich ist sie deckungsgleich mit der Version 1.0.0. Die Version 0.1.0 wird deswegen in noch unspezifizierter Zukunft mit der Ankündigung deprecated bezeichnet und sollte 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 der FITKO hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".