Die Telematikinfrastruktur (TI) 2.0 setzt vollständig auf die Zero‑Trust‑Sicherheitsarchitektur. Damit Primärsysteme (z.B. PVS oder KIS) künftig weiterhin auf TI‑Dienste zugreifen können, z.B. zum Versichertenstammdaten-Abgleich, braucht es den ZETA‑Client. Dieser wird über das ZETA‑SDK implementiert. Dieses SDK übernimmt alle sicherheitsrelevanten Zero‑Trust‑Funktionen und kapselt die komplexen Abläufe, wie Discovery, Registrierung, Authentifizierung und die steuernde Kommunikation mit dem ZETA‑Guard.

In diesem Blogpost erfahren Sie, was das ZETA‑SDK ist, wo Sie die notwendigen Informationen finden, und welche konkreten Schritte zur Integration nötig sind.

Wozu braucht man das ZETA‑SDK?

Der ZETA‑Client ist die Client‑Komponente der Zero‑Trust‑Architektur und bildet gemeinsam mit dem ZETA‑Guard die Sicherheitsbasis der TI 2.0.
Während der Guard serverseitig Zugriffe absichert, kümmert sich der ZETA‑Client darum, dass Client‑Anwendungen sicher und regelkonform über den Guard auf Fachdienste (z.B. VSDM) zugreifen.

Das Zero Trust SDK ist eine Bibliothek, die im Primärsystem eingebunden werden kann, um den Zero Trust Client zu integrieren. Das SDK wird von der gematik bereitgestellt und:

• ist in Kotlin Multiplatform entwickelt
• kapselt komplexe Abläufe wie:
  • Erzeugung, sichere Speicherung und Prüfung der kryptographischen App/Geräte Identität
  • Erzeugung der App/Gerät-Attestierung und Ermittlung und Übertragung der Eigenschaften der Laufzeitumgebung (Betriebssystem, Betriebssystem Version, etc.)
  • Implementierung des OAuth Flows
  • Management der Sessions inkl. Verwaltung der Access und Refresh Token.
  • Management der Clientregistrierungen

Das SDK wirkt weitestgehend transparent, d. h. bestehende Clientlogik kann weiter genutzt und vorhandene Funktionen (Token‑Handling, Secure Storage) in das SDK integriert werden.

Wie binde ich das ZETA-SDK ein?

Bevor Sie das ZETA‑SDK in Ihr Primärsystem integrieren, lohnt sich ein kurzer Überblick über die wichtigsten Zero‑Trust‑Komponenten und die notwendigen Voraussetzungen. Die folgenden Schritte führen Sie kompakt durch den Integrationsprozess, von den Grundlagen des ZETA‑Clients über die Registrierung und SDK‑Einbindung bis hin zum Testen.

Schritt 1: Lernen Sie Ihr neues Zero-Trust-Team kennen

Der ZETA-Client:

• integriert sich in Primärsysteme
• stellt bei Bedarf eine sichere Verbindung per ASL-Verschlüsselung zu dem ZETA Guard des jeweiligen Fachdiensts her
• sammelt Nachweise für die Integrität und Vertrauenswürdigkeit des Primärsystems
• führt die OAuth‑basierenden Anmeldeprozesse durch
• verwaltet Sitzungen sowie die zugehörigen Access‑ und Refresh‑Tokens
• übernimmt die Organisation und Pflege der Client‑Registrierungen

Das ZETA-SDK:

• ist eine Bibliothek, die im Primärsystem eingebunden werden kann, um den Zero Trust Client zu integrieren
• kapselt komplexe Abläufe des ZETA-Clients

Der ZETA-Guard:

• schützt TI‑2.0‑Dienste vor unberechtigtem Zugriff
• setzt aktuelle Sicherheitsrichtlinien um
• überwacht alle Zugriffe
• prüft die Integrität von Clients und Diensten, um Angriffe oder Veränderungen zu erkennen
• setzt aktuelle Sicherheitsrichtlinien am Policy Decision Point (PDP) um
• überwacht alle Zugriffe am Policy Enforcement Point (PEP)

Schritt 2: Holen Sie sich die richtigen Unterlagen

Wichtiges steht in:

• dem ZETA‑Produkthandbuch
• der ZETA-Spezifikation der gematik
• dem SDK‑Integrationsguide

Schritt 3: Prüfen Sie Ihre Voraussetzungen

Bevor Sie den ersten Code schreiben benötigen Sie:

✔ Zugriff auf die ZETA‑SDK Artefakte (Maven Repository für Kotlin/Java)
✔ gültige SM‑B Datei im .p12-Format (aus dem Vertrauensraum)
✔ Build‑Tool Maven
✔ Zugriff auf Test‑Fachdienst oder Test‑Guard‑Setup (z. B. via KIND oder Testdriver)

Optional – je nach Ausbaustufe:

✔ TPM‑Daten (wenn TPM‑Attestation genutzt wird)

Schritt 4: Registrieren Sie Ihren Client

Für die Nutzung von TI 2.0 Diensten muss der ZETA-Client bei der gematik registriert und folgende Daten hinterlegt werden:

• Client‑ID (die Beantragung neuer Client-IDs erfolgt über das Fachdienst-Portal der gematik)
• Produktversion des Clients (inkl. genutzter ZETA‑SDK‑Version und zugehöriger Fachdienste)
• ggf. TPM-/Hash-Attestierung, falls verwendet wird (um in die OPA-Regeln aufgenommen zu werden)

Schritt 5: Importieren Sie das SDK

Wenn Sie das SDK in Ihre eigenen Kotlin/Java-Projekte einbinden möchten, können Sie es bereits aus einem Maven-Repository beziehen.

Fügen Sie dazu diese Abhängigkeit zu Ihrer Maven-POM-Datei hinzu:

<!-- https://mvnrepository.com/artifact/de.gematik.zeta/zeta-sdk-jvm --> 
<dependency> 
  <groupId>de.gematik.zeta</groupId> 
  <artifactId>zeta-sdk-jvm</artifactId> 
  <version>x.y.z</version> 
</dependency>

Schritt 6: Erzeugen Sie eine ZETA‑Client‑Instanz

Über die statische Methode build(resource, BuildConfig) wird eine neue SDK-Client-Instanz erzeugt.

Sie sagen dem SDK:

• Wer bin ich? (Produkt‑ID, Client‑Name)
• Welche Version habe ich?
• Wo speichere ich Tokens?
• Wo ist mein Fachdienst?
• Welche Token/Scopes brauche ich?

Anschließend haben Sie einen Zero‑Trust‑fähigen Client.

Gleichzeitig ermöglicht es dem Client, bereits implementierte Funktionen wie die Speicherung, Konfiguration oder den Abruf eines SM(C)-B-Tokens wiederzuverwenden. Obwohl Implementierungen für diese Themen bereitgestellt werden, können aufgrund der modularen Struktur und der Konfigurationsparameter bei der Instanziierung des ZETA SDK clientseitige Implementierungen in das SDK eingebunden werden

Schritt 7: Bauen Sie den HTTP‑Client in Ihre Anwendung ein

Das SDK stellt eine Methode httpClient() bereit. Diese gibt einen fertigen HTTP-Client mit Methoden zurück, die hinter den Kulissen die ZETA-spezifischen Funktionen übernehmen.

Das Primärsystem ruft TI-Fachdienste nun über den ZETA‑HTTP‑Client auf.

Schritt 8: Testen Sie’s!

Um die Einbindung des ZETA‑Clients über das ZETA‑SDK technisch zu überprüfen, können Primärsystemhersteller den vollständigen Ende‑zu‑Ende‑Testlauf der bereitgestellten Testsuite nutzen. Die Tests validieren, ob der Client korrekt mit den Cloud‑ bzw. lokalen ZETA‑Diensten interagiert, die API‑Anforderungen erfüllt und alle notwendigen Abläufe nachvollziehbar reproduziert. Dafür stehen unterschiedliche Ausführungswege zur Verfügung → lokal, in Containern oder automatisiert in CI/CD‑Pipelines.

Die notwendigen Schritte und Varianten für die Integrationstests sind ausführlich in den folgenden Anleitungen beschrieben:

• Wie Sie einen Ende-zu-Ende Integrationstest ausführen
  (führt durch die vollständige Testausführung inkl. Parameter, Testumgebung, Tags)
• Wie Sie den Testdriver nutzen
  (erläutert die zentrale Testlauf‑Logik und die Konfiguration über Umgebungsvariablen)
• Wie Sie den Testdriver als Container erstellen
  (beschreibt Bau und Ausführung des Docker‑Images für reproduzierbare Testläufe)