Zum Hauptinhalt springen

Übersicht

SDKs für FIT-Connect

Dieser Bereich beschreibt die Software Development Kits (SDKs), die Entwickler:innen nutzen können, um sendende und empfangende Systeme einfacher an FIT-Connect anzubinden.

Was sind SDKs für FIT-Connect?

Die SDKs für FIT-Connect sind Software-Bibliotheken, die die FITKO (Föderale IT-Kooperation) für Software-Projekte bereitstellt, sodass die Entwickler:innen dieser Projekte einen leichteren Zugriff auf die Funktionen von FIT-Connect erhalten. Verfügbar sind ein SDK für .NET, für Java und für JavaScript.

Vorteile durch SDKs

Mit den SDKs für FIT-Connect müssen Software-Entwickler:innen nicht mehr selbst 100 Prozent der Software programmieren, um über FIT-Connect Nachrichten (Einreichungen) an einen Empfänger (ein Fachverfahren) zu senden (oder um solche Nachrichten zu erhalten).
Zudem müssen zum Beispiel die Entwickler:innen von sendenden Systemen nicht selbst die Metadaten zu den Einreichungen erstellen und verschlüsseln (und empfangende System müssen nicht selbst diese Metadaten entschlüsseln und prüfen). Stattdessen binden Entwickler:innen ein SDK in ihre Programme ein und rufen Funktionen dieses SDKs in ihren Programmen auf.
Das SDK kapselt die RestAPI von FIT-Connect und kümmert sich intern um viele sicherheitsrelevante und notwendige Aufgaben, die sonst von der nutzenden Software erledigt werden müssten.

SDKs in mehreren Programmiersprachen

Die SDKs für den Zugriff auf FIT-Connect werden in den Programmiersprachen Java, C# und JavaScript angeboten, sodass viele Entwickler:innen in ihrer gewohnten Programmiersprache und Entwicklungsumgebung arbeiten können.

JavaScript-SDK für Onlinedienste

Das JavaScript-SDK unterstützt Software-Entwickler:innen bei der Anbindung eines Onlinedienstes an FIT-Connect. Unter einem "Onlinedienst" wird hier eine Webseite oder App verstanden, die es den Anwendern:innen erlaubt, Einreichungen (Submissions) über FIT-Connect an ein Fachverfahren zu senden.
Software-Entwickler:innen, die einen solchen Onlinedienst erstellen, können das JavaScript-SDK verwenden, um zum Beispiel die zu sendenden Anträge zu verschlüsseln.
Jedoch kann das JavaScript-SDK allein keine Einreichungen an FIT-Connect senden. Dazu ist zusätzlich eine Backend-Applikation auf einem Server nötig. Zur Implementierung des Backends kann das Java-SDK oder das .NET-SDK verwendet werden.

Sonderstellung des JavaScript-SDKs

Der große Vorteil des JavaScript-SDKs ist die Möglichkeit, die Antragsdaten bereits im Browser der Antragsstellenden zu verschlüsseln. Wird dagegen nur das .NET-SDK (oder nur das Java-SDK) verwendet, dann können die Antragsdaten erst im Backend verschlüsselt werden.

Sequenzdiagramm: JavaScript-SDK und Backend

Das folgende Diagramm zeigt den Ablauf einer Submission (Einreichung) von einer Webseite oder App aus: Das JavaScript-SDK wird genutzt, um eine Einreichung zu verschlüsseln. Anschließend sendet der Onlinedienst (Webseite oder App) die verschlüsselte Einreichung über ein Backend an FIT-Connect. Das adressierte Fachverfahren holt anschließend die Einreichung von FIT-Connect ab (im Diagramm nicht dargestellt). Der Onlinedienst sendet Anfragen zum Status einer Einreichung über das Backend an FIT-Connect.

sequenceDiagram; actor user as Browser / App; participant js as JS SDK; participant backend as Backend; participant fitko as FIT-Connect; user->>js: Eingabe der Daten; js->>backend: PublicKey anfordern; backend->>js: ; js->>js: Verschlüsselung; Note right of js: Verschlüsselung der Submission direkt im Browser; js->>user: Encrypted Submission; user->>backend: Submission übertragen; backend->>fitko: Submission ankündigen; fitko->>backend: SubmissionId; backend->>fitko: Submission senden; fitko->>backend: CaseId; backend->>user: CaseId, SubmissionId; user->>backend: Status der Submission anfragen; backend->>fitko: Abruf des EventLogs / Status; fitko->>backend: ; backend->>user: Status;

Sender und Empfänger

Sie können mit dem .NET- und dem Java-SDK sowohl einen Sender als auch einen Empfänger implementieren. Die SDKs erleichtern Entwickler:innen den Zugriff auf die Dienste, die die FITKO bereitstellt, zum Beispiel den Zugriff auf den Zustelldienst oder den Routingdienst.
Wenn Sie ein SDK für den Zugriff auf diese Dienste einsetzen, dann rufen Sie nicht selbst in Ihrem Programmcode die Schnittstellen (WebAPIs) der Dienste auf und versorgen sie mit den erforderlichen Werten. Sie erzeugen stattdessen Objekte (Sender, Subscriber) und rufen an diesen Objekten Methoden auf. Und diese Methoden führen dann intern alle erforderlichen Aufrufe der Dienste durch. Zudem prüfen die Methoden auch die Werte, die von den aufgerufenen Diensten zurückgeliefert werden.
Dadurch sind Entwickler:innen von den vielen Details der Aufrufe entlastet.

Voraussetzungen für den Zugang zu FIT-Connect

Für den Zugang zu FIT-Connect ist es erforderlich, dass Sie für sendende Systeme (zum Beispiel für einen Onlinedienst) einen Client des Typs "Sender" anlegen. Eine Beschreibung dazu finden Sie hier.
Für empfangende Systeme (Fachverfahren) müssen Sie einen Client des Typs "Subscriber" sowie einen Zustellpunkt anlegen. Eine Beschreibung dazu finden Sie hier.
Diese Voraussetzungen müssen für den Zugang zu FIT-Connect erfüllt sein, unabhängig davon, ob Sie ein SDK verwenden oder nicht.

Verfügbarkeit der SDKs

Die FITKO entwickelt und pflegt die SDKs. Den aktuellen Stand der Verfügbarkeit sehen Sie auf der Seite Roadmap.

Funktionsumfang des JavaScript-SDKs

Das JavaScript-SDK wendet sich an Entwickler:innen, die einen Onlinedienst (Sender) erstellen, der Einreichungen über FIT-Connect an ein Fachverfahren (Subscriber) sendet. Allerdings kann das JavaScript-SDK nicht direkt Anträge an ein Fachverfahren senden, dafür ist zusätzlich ein Backend erforderlich siehe oben "Ausnahme JavaScript-SDK" Um das Backend zu implementieren, können Entwickler:innen das Java- oder C#-SDK nutzen.
Das SDK wird als MVP (Minimum Viable Product) realisiert: Ein kleines Projekt, das einen kleinen Funktionsbereich zur Verfügung stellt. Die folgende Liste enthält alle Funktionen, die Software-Entwickler:innen mit Hilfe des JavaScript-SDKs implementieren können:

  • Sender: Verschlüsselung von Fachdaten (JSON, XML) mittels JWE (JSON Web Encryption)
  • Sender: Verschlüsselung von Anhängen (Binärdaten, Text) mittels JWE
  • Sender: Korrekte Erzeugung eines Metadatensatzes inklusive der Hashwerte
  • Sender: Parsen von SET (Security Event Token) inklusive der Signaturprüfung
  • Logging

Funktionsumfang des Java- und .NET-SDKs

Funktionen des Senders

  • Korrekte DestinationID über Routing API ermitteln
  • Angabe von Leistungs-ID (serviceIdentifier), Name der Verwaltungsleistung und Fachdatenschema (submissionSchema). Das definierte Schema muss dabei im adressierten Zustellpunkt hinterlegt sein (keine automatische Ermittlung, sondern Prüfung der Übereinstimmung).
  • Optional: Angabe eines Callback für SET-Events (Secret kann vom SDK definiert werden)
  • Bei unverschlüsselter Übergabe von Metadaten, Fachdaten und Anlagen:
    • Übergabe von unverschlüsselten Fachdaten (mimeType: entweder JSON oder XML) und Anlagen (ink. Mimetype, optionalem filename (und optionaler description?); Purpose und attachmentId werden vom SDK festgelegt)
    • Übergabe weiterer Metadaten-Attribute (authenticationInformation, paymentInformation, replyChannel, additionalReferenceInfo) -> ggf. in Folgeissues nach MVP
  • Bei verschlüsselter Übergabe von Metadaten, Fachdaten und Anlagen:
    • Anlage der Submission inkl. Liste der angekündigten Anlagen (announcedAttachments)
    • Angabe von attachmentIds von Anlagen
    • Übergabe von verschlüsselten Metadaten (keine Unterscheidung zw. JSON und XML, da ohnehin verschlüsselt), Fachdaten und Anlagen
  • Submission-Objekt mit allen relevanten Infos erhalten (submissionId, attachmentIds, caseId, authenticationTags, ...)
  • Mit Hilfe des SentSubmission-Objekts den Status einer Submission ermitteln

Funktionen des Subscribers

  • Verfügbare Submissions ermitteln (destinationId, submissionId, caseId)
  • Leistungs-ID (serviceIdentifier), Fachdatenschema (submissionSchema.schemaUri) und Mimetype (submissionSchema.mimeType) der Fachdaten ermitteln
  • attachmentId, mimeType und (falls vorhanden) filename aller Anlagen ermitteln (Prüfung Filename: Pfad ist Länge 1; keine Ordner im Datennamen enthalten)
  • Auf Fachdaten zugreifen (entweder JSON oder XML)
  • Attachment auspacken (binary, json, xml)
  • Auf weitere Metadaten-Attribute zugreifen
  • Empfangsbestätigung oder Zurückweisung senden (accept-/reject-Event)
  • Abruf des Event Log

Lizenz

Der Quellcode ist lizenziert unter EUPL.

Rechtlicher Hinweis

Dieses Software Development Kit (SDK) ist dazu bestimmt, die Anbindung einer Software an die FIT-Connect-Infrastruktur zu ermöglichen. Hierfür kann das SDK in die anzubindenden Software integriert werden. Erfolgt die Integration des SDK in unveränderter Form, liegt keine Bearbeitung im Sinne der EUPL bzw. des deutschen Urheberrechts vor. Die Art und Weise der Verlinkung des SDK führt insbesondere nicht zur Schaffung eines abgeleiteten Werkes. Die unveränderte Übernahme des SDK in eine anzubindende Software führt damit nicht dazu, dass die anzubindende Software unter den Bedingungen der EUPL zu lizenzieren ist. Für die Weitergabe des SDK selbst - in unveränderter oder bearbeiteter Form, als Quellcode oder ausführbares Programm - gelten die Lizenzbedingungen der EUPL in unveränderter Weise.