Java-SDK

Die Föderale IT-Kooperation (FITKO) stellt Entwickler:innen ein Software Development Kit (SDK) für die Anbindung von Java-Anwendungen an FIT-Connect zur Verfügung und ermöglicht die einfache Nutzung der REST-API von FIT-Connect.

Repositories

Das SDK steht in verschiedenen Quellen zur Verfügung:

Maven-Artefakt des SDK-Clients im öffentlichen Repository von Maven-Central
Snapshots, Builds und Tags im Gitlab-Projekt von FIT-Connect
Release Builds und Snapshots im öffentlichen Nexus-Repository von Sonatype

API-Dokumentation

Die API-Dokumentation im Format Javadoc ist hier verfügbar.

Systemvoraussetzungen

Das Java Development Kit (JDK) >= 11 ist erforderlich, um das SDK zu nutzen. Mit dem folgenden Befehl können Sie überprüfen, welche Version des JDKs auf Ihrem Entwicklungsrechner installiert ist:

> java --version
openjdk 11.0.18 2023-01-17 LTS
OpenJDK Runtime Environment Microsoft-7208460 (build 11.0.18+10-LTS)
OpenJDK 64-Bit Server VM Microsoft-7208460 (build 11.0.18+10-LTS, mixed mode)

Integration

Das SDK kann auf verschiedene Wege in bestehende Systeme integriert werden. Neben der Einbindung als Maven-Artefakt gibt es auch die Möglichkeit, den Quellcode des Projektes lokal zu bauen.

Einbindung als Maven-Artefakt

Sie können das SDK in ein Projekt einbinden, indem Sie es als Dependency der Datei pom.xml hinzufügen:

<dependency>
  <groupId>dev.fitko.fitconnect.sdk</groupId>
  <artifactId>client</artifactId>
  <version>[Latest Version]</version>
</dependency>

Mit [Latest Version] als aktuelles Build oder einer Snapshot-Version.

Wird eine Snapshot-Version genutzt, dann ist die Angabe des "Maven Snapshot Repositories" in der POM notwendig:

<repositories>
  <repository>
    <id>maven-snapshots</id>
    <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
  </repository>
</repositories>

SDK lokal bauen

Als Alternative zu Maven kann der Quellcode des Java-SDKs verwendet werden, um das SDK lokal zu bauen. Mit dem Befehl git clone laden Sie das Repository:

git clone https://git.fitko.de/fit-connect/sdk-java.git

Anschließend wird das Projekt gebaut:

./mvnw clean package -DskipTests

Das Client-Artefakt steht nach erfolgreichem Build unter {projekt.dir}/client/target zur Verfügung.

Einrichtung

FIT-Connect verwendet die Credentials ClientId und ClientSecret. Mit diesen Zugangsdaten wird beim OAuth-Server ein Token angefragt, das Zugriff auf die FIT-Connect-Schnittstellen erlaubt (Submission API, Routing API, Self-Service API).

Credentials erzeugen

Im Self-Service-Portal (SSP) von FIT-Connect werden die Zugangsdaten für Sender-Clients und Subscriber-Clients eingerichtet. Beim Anlegen von Clients für einen Sender oder Subscriber sind die Credentials unter Zugangsdaten einsehbar. Dazu finden Sie hier eine Beschreibung.

Bereitstellung der Konfiguration

Sie konfigurieren das SDK mithilfe der Datei config.yml. Eine Vorlage (ein Template) für diese Datei finden Sie hier. In dieser Konfigurationsdatei stellen Sie die folgenden Daten zur Verfügung:

Für das Konfigurieren eines Senders:

clientId - ClientId, das Sie beim Anlegen eines Sender-Clients im Self-Service-Portal (SSP) erhalten haben.
clientSecret - Das dazu gehörende ClientSecret, das Sie beim Anlegen dieses Sender-Clients im Self-Service-Portal (SSP) erhalten haben.

Für das Konfigurieren eines Empfängers:

clientId - ClientId, das Sie beim Anlegen eines Subscriber-Clients im Self-Service-Portal erhalten haben.
clientSecret - Das dazu gehörende ClientSecret, das Sie beim Anlegen dieses Subscriber-Clients im Self-Service-Portal erhalten haben.
privateDecryptionKeyPaths - Pfad(e) zum JWK des privaten Entschlüsselungsschlüssels.
Eine Beschreibung zum Ableiten von JWKs (JSON Web Keys) aus einem Zertifikat finden Sie hier.
privateSigningKeyPath - Pfad zum JWK des privaten Signatur-Schlüssels

Betriebsumgebung (Environments):

Unter dem Schlüssel activeEnvironment stehen die Umgebungen PROD, STAGE und TEST zur Verfügung. Diese sind bereits durch das SDK vorkonfiguriert, die Einstellungen können jedoch, wie im Beispiel zu sehen ist, überschrieben werden.

Beispiel einer Minimalkonfiguration für einen Sender

senderConfig:
  clientId: "07564691-82bd-4b41-b464-4c39aaa0bc0c"
  clientSecret: "la4jl3enU-pS25BS3aFDDuJKmv0N27YIF1tz8AR-3ws"

subscriberConfig:
  clientId:
  clientSecret:

  privateDecryptionKeyPaths:
  privateSigningKeyPath:

activeEnvironment: TEST

Beispiel einer Minimalkonfiguration für einen Subscriber

senderConfig:
  clientId:
  clientSecret:

subscriberConfig:
  clientId: "e5adf182-17d2-42fb-836d-f82f14c87410"
  clientSecret: "lf4jK5enU-pR27BS8aFLLuJYmv0N37YIF8tz8AR-1rw"

  privateDecryptionKeyPaths: ["C:/fit-connect/config/decryption_key.json"]
  privateSigningKeyPath: "C:/fit-connect/config/signing_key.json"

activeEnvironment: TEST

Beispiel optionaler Properties

Die Properties vordefinierter Umgebungen können wie im Beispiel für TEST überschrieben werden. Neben den vordefinierten Umgebungen lassen sich auch ohne Code-Änderung weitere benutzerdefinierte Umgebungen zur Konfiguration hinzufügen (siehe Beispiel CUSTOM_ENVIRONMENT):

# Aktivierung einer benutzerdefinierten Umgebung
activeEnvironment: CUSTOM_ENVIRONMENT

environments:
  # Überschreiben der TEST-Environment und Deaktivieren des Auto-Rejects
  TEST:
    enableAutoReject: false

  # Anlegen einer weiteren benutzerdefinierten Umgebung
  CUSTOM_ENVIRONMENT:
    authBaseUrl: "https://auth-url.test.net"
    routingBaseUrl: "https://routing-url.test.net"
    submissionBaseUrls: ["https://submission-url-1.test.net", "https://submission-url-2.test.net"]
    selfServicePortalBaseUrl: "https://portal-url.test.net"
    enableAutoReject: true
    allowInsecurePublicKey: true
    skipSubmissionDataValidation: false

# explizite Angabe lokal verfügbarer Schema-Pfade zur Validierung der Fachdaten
submissionDataSchemas:
  "urn:test:sample": "some/path/to/file"
  "https://xml.schema.sample.net": "some/path/to/file"
  "https://json.schema.sample.net": "some/path/to/file"

# Angabe einer Proxy-Verbindung
proxyConfig:
  httpProxyHost: "https://proxy.test.net"
  httpProxyPort: 8080
  requestTimeoutInSeconds: 10

Übersicht optionaler Properties

Property	Typ	Scope	Beschreibung
`enableAutoReject`	true/false	Environment	Autom. Abweisung von Submissions sobald beim Empfang eine Validierung fehlschlägt
`allowInsecurePublicKey`	true/false	Environment	Erlaubt die Nutzung von Self-Signed-Zertifikaten für Testzwecke
`skipSubmissionDataValidation`	true/false	Environment	Validierung der Fachdaten gegen die in der Submission angegebene Schema-URI
`submissionDataSchemas`	Pfade (Strings) zu den lokalen Schemata für Fachdaten	Config	Schemata gegen die in der Submission angegebene Fachdaten validiert werden. Sind keine lokalen Schemata definiert, wird versucht, das Schema über HTTP zu laden. Hinweis: URNs, die nicht über HTTP adressierbar sind, sollten hier als Datei hinterlegt werden.

Laden der Konfiguration

Über den ApplicationConfigLoader kann die Konfiguration an die Clients für Sender, Empfänger und Router übergeben werden. Im folgenden Beispiel wird die Datei config.yml aus einem Pfad geladen:

final ApplicationConfig config = ApplicationConfigLoader.loadConfigFromPath(Path.of("path/to/config.yml"));

Sie können dem ApplicationConfigLoader die Konfiguration auch als String (im YAML-Format) übergeben. Zudem besteht die Möglichkeit, den Pfad zur Konfigurationsdatei über die Umgebungsvariable FIT_CONNECT_CONFIG bereitzustellen, wie das folgende Beispiel zeigt:

set FIT_CONNECT_CONFIG="C:/sdk/config/config.yaml"

final ApplicationConfig config = ApplicationConfigLoader.loadConfigFromEnvironment();

Erzeugung konfigurierter Clients

Mittels der ClientFactory und einer zuvor geladenen Konfiguration können Clients für Sender, Subscriber und Router erzeugt werden.

final SenderClient senderClient = ClientFactory.getSenderClient(config);
final SubscriberClient subscriberClient = ClientFactory.getSubscriberClient(config);
final RouterClient routerClient = ClientFactory.getRouterClient(config);

Übersicht der Umgebungen

Die folgenden Umgebungen stehen vorkonfiguriert über das SDK bereit:

	PROD	STAGE	TEST
AuthBaseURL	https://auth-prod.fit-connect.fitko.net	https://auth-refz.fit-connect.fitko.net	https://auth-testing.fit-connect.fitko.dev
RoutingBaseURL	https://routing-api-prod.fit-connect.fitko.net	https://routing-api-prod.fit-connect.fitko.net	https://routing-api-testing.fit-connect.fitko.dev
SubmissonBaseURLs	[https://submission-api-prod.fit-connect.niedersachsen.de]	[https://submission-api-refz.fit-connect.niedersachsen.de]	[https://submission-api-testing.fit-connect.fitko.dev]
SelfServicePortalBaseURL	https://portal.auth-prod.fit-connect.fitko.net	https://portal.auth-refz.fit-connect.fitko.net	https://portal.auth-testing.fit-connect.fitko.dev
enableAutoReject	true	true	true
allowInsecrurePublicKey	false	false	true
skipSubmissionDataValidation	false	false	false

Java-SDK

Repositories​

API-Dokumentation ​

Systemvoraussetzungen​

Integration​

Einbindung als Maven-Artefakt​

SDK lokal bauen​

Einrichtung​

Credentials erzeugen​

Bereitstellung der Konfiguration​

Für das Konfigurieren eines Senders:​

Für das Konfigurieren eines Empfängers:​

Betriebsumgebung (Environments):​

Beispiel einer Minimalkonfiguration für einen Sender​

Beispiel einer Minimalkonfiguration für einen Subscriber​

Beispiel optionaler Properties​

Übersicht optionaler Properties​

Laden der Konfiguration​

Erzeugung konfigurierter Clients​

Übersicht der Umgebungen​