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.

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.

.NET (SDK)

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 von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".

---

Java

  public Map<String, Object> toEventPayloadMap() {
    final HashMap<String, Object> authenticationTags = new HashMap<>(3);
    authenticationTags.put("metadata", metadata);
    if (data != null) {
      authenticationTags.put("data", data);
    }
    if (!attachments.isEmpty()) {
      authenticationTags.put("attachments", Collections.unmodifiableMap(attachments));
    }
    return Map.of(
      "authenticationTags",
      authenticationTags
    );
  }

C#

// TBD

JavaScript

// TBD

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.

.NET (SDK)

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

---

Java

  public Map<String, Object> toEventPayloadMap() {
    final ArrayList<Map<String, Object>> problemList = new ArrayList<>();
    for (Problem problem : problems) {
      final HashMap<String, Object> problemMap = new HashMap<>(problem.getParameters());
      final URI type = problem.getType();
      if (type != null) {
        problemMap.put("type", type);
      }
      final String title = problem.getTitle();
      if (title != null) {
        problemMap.put("title", title);
      }
      final StatusType status = problem.getStatus();
      if (status != null) {
        problemMap.put("status", status);
      }
      final String detail = problem.getDetail();
      if (detail != null) {
        problemMap.put("detail", detail);
      }
      final URI instance = problem.getInstance();
      if (instance != null) {
        problemMap.put("instance", instance);
      }
      problemList.add(problemMap);
    }
    return Map.of("problems", problemList);
  }

---

C#

// TBD

JavaScript

// TBD

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

.NET (SDK)

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

---

Java

Das Erzeugen eines SETs besteht aus drei Schritten.

  public static SignedJWT buildEvent(String issuer, UUID caseId, UUID submissionId, FitConnectEvent event, Map<String, Object> payload, JWK jwk) {
    try {
      final FitConnectSET set = new FitConnectSET("" + issuer, "submission:" + submissionId, "case:" + caseId);
      set.addEvent(event, payload);
      return set.sign(jwk);
    } catch (ParseException | JOSEException ex) {
      throw new FitConnectClientException(ex.getMessage(), ex);
    }
  }

SET anlegen

Im Konstruktor der Klasse FitConnectSET wird das JWTClaimsSet erzeugt. Als Claim events wird eine später zu befüllende Map eingesetzt.

  public FitConnectSET(String issuer, String subject, String transactionId) {
    UUID jti = UUID.randomUUID();
    this.events = new HashMap<>();
    this.claimsSet = new JWTClaimsSet.Builder()
      .claim(CLAIM_SCHEMA, FitConnect.SET_PAYLOAD_SCHEMA_TO_USE)
      .issuer(issuer)
      .issueTime(new Date())
      .jwtID(jti.toString())
      .subject(subject)
      .claim("events", events)
      .claim("txn", transactionId)
      .build();
  }

Event Payload hinzufügen

Im zweiten Schritt wird das Event, ggf. mit Payload hinzugefügt.

  public void addEvent(FitConnectEvent event, Map<String, Object> payload) {
    if (signedJWT != null || event == null) {
      throw new UnsupportedOperationException("Im aktuellen Zustand kann kein Event hinzugefügt werden.");
    }
    events.put(event.getFullName(), payload == null ? Collections.emptyMap() : payload);
  }

SET erstellen & signieren

Im letzten Schritt wird das SET erstellt und signiert.

  public SignedJWT sign(JWK key) throws JOSEException, ParseException {
    JWSSigner signer = new RSASSASigner(key.toRSAKey());
    JWSHeader header = JWSHeader.parse(Map.of(
      "typ", HEADER_TYPE,
      "kid", key.getKeyID(),
      "alg", "PS512"
    ));
    this.signedJWT = new SignedJWT(header, claimsSet);
    signedJWT.sign(signer);
    return signedJWT;
  }

---

C#

// TBD

JavaScript

// TBD