Elektronische Gesundheitskarte und Telematikinfrastruktur





Spezifikation

Verzeichnisdienst FHIR-Directory




    

     

      Version
      1.6.0
     

     

      Revision
      1181211
     

     

      Stand
      20.02.2025
     

     

      Status
      freigegeben
     

     

      Klassifizierung
      öffentlich
     

     

      Referenzierung
      gemSpec_VZD_FHIR_Directory

Dokumentinformationen

Änderungen zur Vorversion

Anpassungen des vorliegenden Dokumentes im Vergleich zur Vorversion können Sie der nachfolgenden Tabelle entnehmen.

Dokumentenhistorie

Version Stand Kap./ Seite Grund der Änderung, besondere Hinweise Bearbeitung
1.0.0  01.10.2021 Erstversion des Dokumentes   gematik
1.1.0 29.07.2022 Fortschreibung und insbesondere Anpassungen gemäß TI-Messenger-Spezifikation Version 1.1.0 gematik
1.2.0 12.12.2022 4.2.4

4.2.3
4.3.1
 Fachliche Beschreibung Operation whereIs ergänzt - C_11233
Aufbau der Föderationsliste aktualisiert - ANFTIM-185
Sicherheits- und Datenschutzanforderungen ergänzt		 gematik
1.3.0 31.07.2023 Einarbeitung TI-Messenger Maintenance 23.1 / VZD FHIR Maintenance_23.1 gematik
1.4.0 30.01.2024 4.2.1.5, 5.2

2, 2.1		 Authentisierung mit SMC-B/HBA für die /search Schnittstelle ermöglicht (z.B. für ePA Ombudsstelle), 
Systemüberblick entsprechend der Änderungen aktualisiert
 gematik
1.5.0 22.03.2024 Anpassungen gemäß Änderungsliste VZD_23.2 und _24.1 gematik
1.6.0 20.02.2025 Anpassungen gemäß Änderungsliste VZD_25.1 gematik

Inhaltsverzeichnis

1 Einordnung des Dokumentes

Dieses Dokument beschreibt das FHIR-Directory des Verzeichnisdienstes der TI. Die Spezifikation umfasst Schnittstellen zum Abruf von Informationen der im FHIR-Directory eingetragenen Organization-FHIR-Ressourcen und der Practitioner-FHIR-Ressourcen durch Clientsysteme sowie Schnittstellen und Prozesse zur Pflege der Informationen innerhalb des VZD-FHIR-Directories.

1.1 Zielsetzung

Die Spezifikation soll die Entwicklung und den Betrieb eines VZD-FHIR-Directories für die Telematikinfrastruktur unterstützen, indem die funktionalen und nicht-funktionalen Anforderungen sowie die Sicherheits-Anforderungen an den Dienst festgelegt werden. 

1.2 Zielgruppe

Das Dokument richtet sich zwecks der Realisierung an den Hersteller des VZD-FHIR-Directories sowie an den Anbieter, welcher dieses Produkt betreibt [gemKPT_Betr]. Alle Hersteller und Anbieter von TI-Anwendungen, die das VZD-FHIR-Directory nutzen, müssen dieses Dokument ebenso berücksichtigen. Gleichfalls ist das Dokument auch für die Nutzer relevant, welche die Daten im VZD-FHIR-Directory eintragen, abfragen, ändern und löschen wollen.

1.3 Geltungsbereich

Dieses Dokument enthält normative Festlegungen zur Telematikinfrastruktur des deutschen Gesundheitswesens. Der Gültigkeitszeitraum der vorliegenden Version und deren Anwendung in Zulassungs- oder Abnahmeverfahren wird durch die gematik GmbH in gesonderten Dokumenten (z. B. gemPTV_ATV_Festlegungen, Produkttypsteckbrief, Anbietertypsteckbrief u.a.) oder Webplattformen (z. B. gitHub u.a.) festgelegt und bekanntgegeben.

Schutzrechts-/Patentrechtshinweis

Die nachfolgende Spezifikation ist von der gematik allein unter technischen Gesichtspunkten erstellt worden. Im Einzelfall kann nicht ausgeschlossen werden, dass die Implementierung der Spezifikation in technische Schutzrechte Dritter eingreift. Es ist allein Sache des Anbieters oder Herstellers, durch geeignete Maßnahmen dafür Sorge zu tragen, dass von ihm aufgrund der Spezifikation angebotene Produkte und/oder Leistungen nicht gegen Schutzrechte Dritter verstoßen und sich ggf. die erforderlichen Erlaubnisse/Lizenzen von den betroffenen Schutzrechtsinhabern einzuholen. Die gematik GmbH übernimmt insofern keinerlei Gewährleistungen.

1.4 Abgrenzungen

Spezifiziert werden in dem Dokument nur die mit dem VZD-FHIR-Directory neu eingeführten Komponenten und Schnittstellen des Verzeichnisdienstes der TI. Das VZD-LDAP-Directory ist in [gemSpec_VZD] spezifiziert. 

Benutzte Schnittstellen werden in der Spezifikation desjenigen Produkttypen beschrieben, der diese Schnittstelle bereitstellt. Auf die entsprechenden Dokumente wird referenziert (siehe auch Anhang, Kapitel 7.5 Referenzierte Dokumente).

Die vollständige Anforderungslage für den Produkttyp ergibt sich aus weiteren Konzept- und Spezifikationsdokumenten, diese sind in dem Produkttypsteckbrief des Produkttyps VZD-FHIR-Directory verzeichnet.

1.5 Methodik

Die Spezifikation ist im Stil einer RFC-Spezifikation verfasst. Dies bedeutet: 

Anwendungsfälle und Akzeptanzkriterien als Ausdruck normativer Festlegungen werden als Grundlage für Erlangung der Zulassung durch Tests geprüft und nachgewiesen. Sie besitzen eine eindeutige, permanente ID, welche als Referenz verwendet werden SOLL. Die Tests werden gegen eine von der gematik gestellte Referenz-Implementierung durchgeführt. 

Anwendungsfälle und Akzeptanzkriterien werden im Dokument wie folgt dargestellt:
<ID> - <Titel des Anwendungsfalles / Akzeptanzkriteriums>
 Text / Beschreibung
[<=]

Die einzelnen Elemente beschreiben:

Dabei umfasst der Anwendungsfall bzw. das Akzeptanzkriterium sämtliche zwischen ID und Textmarke [<=] angeführten Inhalte.

Der für die Erlangung einer Zulassung notwendige Nachweis der Erfüllung des Anwendungsfalls wird in den jeweiligen Steckbriefen festgelegt, in denen jeweils der Anwendungsfall gelistet ist. Akzeptanzkriterien werden in der Regel nicht im Steckbrief gelistet.

Hinweis auf offene Punkte

Offener Punkt: Das Kapitel wird in einer späteren Version des Dokumentes ergänzt.

2 Systemüberblick

Das VZD-FHIR-Directory ist eine Erweiterung des bisherigen Verzeichnisdienstes der TI. Im VZD-FHIR-Directory werden Einträge von Organisationen und Leistungserbringern gespeichert. Die VZD-LDAP-Directory Einträge werden in das VZD-FHIR-Verzeichnis synchronisiert. Bei diesem Vorgang erfolgt eine Umsetzung von der LDAP-Datenstruktur auf die Datenstruktur der FHIR-Ressourcen. Personeneinträge der Leistungserbringer werden auf die PractitionerDirectory-Ressource und Organisations-Einträge auf die OrganizationDirectory-Ressource abgebildet. Die synchronisierten Einträge bilden die Basis-Einträge, die durch die Besitzer um zusätzliche Daten ergänzt bzw. erweitert werden können. PractitionerDirectory und OrganizationDirectory sind Profilierungen der FHIR-Ressourcen Practitioner und Organization. Die Anbieter von Fachanwendungen werden ebenfalls als OrganizationDirectory-Einträge im FHIR-Directory eingetragen, um Daten der Fachanwendung zu dieser Organisation zuordnen zu können.

Der Besitzer einer Telematik-ID erhält das Recht, seinen Eintrag zu erweitern (um z. B. Unterstrukturen für eine Organisation einzutragen) und Fachdaten zu ergänzen (z. B. TI-Messenger-Adressen). Die von den Kartenherausgebern eingetragenen Daten dürfen durch die Besitzer nicht verändert werden. Zusätzliche FHIR-Ressourcen (wie z. B. Endpoint und HealthcareService) können durch die Besitzer ergänzt werden, um den Komfort bei der Suche nach Einträgen zu erhöhen.

Alle vom VZD-FHIR-Directory bereitgestellten Schnittstellen sind über das Internet erreichbar und TLS-gesichert. Die Authentisierung erfolgt mit:

Eine Nutzung der Schnittstellen des VZD-FHIR-Directory ohne Authentisierung der Nutzer MUSS durch das VZD-FHIR-Directory verhindert werden.

Als erste Anwendung wird der TI-Messenger-Dienst das VZD-FHIR-Directory nutzen.

Abbildung 1: Systemüberblick VZD-FHIR-Directory

Das FHIR-Directory ist eine Implementierung der FHIR-Spezifikation (http://hl7.org/fhir/summary.html ).

2.1 Nutzer und Rollen

Tabelle 1: Nutzer und Rollen 

Nutzer und Rolle Beschreibung
Nutzer Alle Nutzer können im FHIR-Directory über die Schnittstelle (1) nach Einträgen im Organisationsverzeichnis und im Personenverzeichnis suchen. 
Org-Admin oder LE Administratoren der Organisationen und LE können im FHIR-Directory über die Schnittstelle (2) ihren Eintrag im Organisationsverzeichnis ändern und um zusätzliche Ressourcen erweitern.

Tabelle 2: Kommunikationsbeziehungen zu IT-Systemen

IT-Systeme Beschreibung
Kartenherausgeber Die Kartenherausgeber nutzen die Schnittstelle (3), um die Einträge ihrer Mitglieder im LDAP-Directory und zukünftig im FHIR-Directory zu pflegen.
TI-Messenger-Anbieter Die TI-Messenger-Anbieter nutzen die Schnittstelle (4), um die Föderationsliste des TI-Messengers abzufragen und um die Domains der von ihnen betriebenen Messenger-Services als Teil der TI-Messenger Föderation zu verwalten.
Fachdienst Fachdienste können sich beim FHIR-Directory Anbieter registrieren und nach Authentisierung search-access_token beziehen (7). Diese search-access_token können sie an ihre Clients verteilen.
gematik Die gematik kann über die Schnittstelle (5) lesend auf die Einträge im FHIR-Directory und im LDAP-Directory zugreifen, um die Daten-Qualität der Einträge zu prüfen und um Fehler zu analysieren.
LDAP-Directory Die Schnittstelle (6) zwischen FHIR-Directory und LDAP-Directory wird vom Verzeichnisdienst genutzt, um die Einträge zu synchronisieren.

Alle Schnittstellen mit Ausnahme (6) sind über das Internet erreichbar. Die Schnittstellen stellen folgende Funktionen bereit:

  1. Für Nutzer gibt es eine Schnittstelle zur Suche nach Einträgen im FHIR-Directory Organisationsverzeichnis und Personenverzeichnis. Die Schnittstelle kann nur nach erfolgreicher Authentisierung genutzt werden. Alle TI-Messenger Nutzer können sich authentisieren und bekommen vom FHIR-Directory ein Accesstoken ausgestellt, das für die Suchanfragen verwendet wird. Die Suche ermöglicht es, komfortabel nach Volltext oder nach bestimmten Werten der einzelnen Attribute über die verlinkten Ressourcen zu suchen. Gefundene Ressourcen werden in einem Bundle von FHIR Ressourcen zurück geliefert. Das Datenformat ist json.
  2. Für Administratoren der Organisationen des Gesundheitswesens und für LE gibt es eine Schnittstelle zur Änderung ihres Eintrags im Organisationsverzeichnis. Zur Nutzung der Schnittstelle ist eine Authentifizierung mit OIDC Authorization Code Flow erforderlich. Über diese Schnittstelle kann im Organisationsverzeichnis der eigene Eintrag der Organisation über eine Verlinkung um zusätzliche Einträge erweitert werden. TI-Messenger Nutzer, die auch LE sind, können diese Schnittstelle nutzen, um ihre TI-Messenger-Adresse in ihrem Eintrag im Personenverzeichnis zu speichern, sodass sie von anderen LE gefunden werden können. Auch hier erfolgt die Authentifizierung über OIDC. Das FHIR-Datenformat ist json.
  3. Für Kartenherausgeber gibt es die Schnittstelle I_Directory_Administration, um Einträge im LDAP-Directory anzulegen und zu pflegen. Das Datenformat ist json und ist in der OpenAPI-yaml-Datei DirectoryAdministration.yaml festgelegt. Zukünftig ist vorgesehen, dass die Kartenherausgeber auch direkt die Schnittstelle zum FHIR-Directory nutzen können. Dann ist das Datenformat FHIR in der Ausprägung JSON. Die Authentifizierung der Kartenherausgeber erfolgt mit OAuth Client Credential Flow.
  4. TI-Messenger-Fachdienste pflegen im FHIR-Directory für die von ihnen angebotenen Messenger-Services die TI-Messenger-Domänen. Zusätzlich können die TI-Messenger-Anbieter die Föderationsliste abfragen. Sie beinhaltet alle an der Föderation des TI-Messengers beteiligte Domains. Um die Kommunikationskontrolle zu ermöglichen, fragen TI-Messenger-Fachdienste auch ab, in welchem Verzeichnis (Personen- oder Organisationsverzeichnis) sich die TI-Messenger-Adressen befinden. Die Authentifizierung der TI-Messenger-Fachdienste erfolgt mit OAuth Client Credential Flow.
  5. Fachdienste können - nach Registrierung beim FHIR-Directory-Anbieter - search-access_token beziehen. Diese search-access_token können sie an ihre Clients verteilen.
  6. Die gematik hat Schnittstellen, um die Daten-Qualität der Einträge zu prüfen. Dazu wird die Schnittstelle der Kartenherausgeber genutzt. Die gematik hat aber nur Leserechte.
  7. Die Einträge im LDAP-Directory werden in das FHIR-Directory Organisations- und Personenverzeichnis synchronisiert. Es handelt sich um eine interne Schnittstelle des Verzeichnisdienstes der TI.

2.2 Nachbarsysteme

Die Nachbarsysteme des VZD-FHIR-Directory sind Client- und Serverkomponenten des TI-Messenger-Dienstes, das VZD-LDAP-Directory, die IDPs aus der TI-IDP-Föderation und die Betriebsdatenerfassung der gematik. 

ML-123876 - Test gegen die Referenzimplementierung der Nachbarsysteme (VZD-FHIR-Directory)

Es MÜSSEN alle Anwendungsfälle des VZD-FHIR-Directories erfolgreich gegen die Referenzimplementierung der Nachbarsysteme getestet sein.
[<=]

3 Zerlegung des Produkttyps

Die folgende Abbildung zeigt die Teilkomponenten des bisherigen VZD-LDAP-Directory und die rot dargestellten neuen Komponenten des VZD-FHIR-Directory.

Abbildung 2: Zerlegung des VZD

Das VZD-FHIR-Directory besteht aus den Komponenten FHIR-Proxy und FHIR-Directory sowie Auth-Service.

Die vom VZD-FHIR-Directory zu liefernden Rohdaten zur Ermittlung der Auslastung und Performance werden in den bereits vorhandenen Betriebsdaten-Erfassungs-Client (BDE-Client) des Verzeichnisdienstes integriert.

4 Funktionsmerkmale

In diesem Kapitel werden die Komponenten des VZD-FHIR-Directories beschrieben.

Das FHIR-Directory stellt folgende Schnittstellen bereit:

Stellt Accesstokens zum Zugriff auf FHIRDirectory APIs aus. Es wird zukünftig zum anwendunsspezifischen Policy Decision Point (PDP) ausgebaut.

Hierbei werden die folgenden REST-Schnittstellen

verwendet. Die Schnittstelle /tim-authenticate erwartet ein Matrix-OpenID-Token, wohingegen bei der Schnittstelle /owner-authenticate ein ID_TOKEN übergeben werden muss. Die Schnittstelle /service-authenticate akzeptiert ein service-authz-token.

Die REST-Schnittstelle /search ermöglicht die Suche nach Personen und Institutionen.

Genutzt wird die Standard FHIR Suchoperation https://build.fhir.org/search.html 

Zur Nutzung der Suchoperation muss ein entsprechendes Accesstoken vom FHIRDirectoryAuthorizationService vorliegen.

Die REST-Schnittstelle /fdv/search ermöglicht die Suche durch Versicherte nach Personen und Institutionen.

Genutzt wird die Standard FHIR Suchoperation https://build.fhir.org/search.html 

Zur Nutzung der Suchoperation muss ein entsprechendes Accesstoken vom FHIRDirectoryAuthorizationService vorliegen.

Die REST-Schnittstelle /tim-provider-services ermöglicht die eigenverantwortliche Verwaltung von Föderationslisteneinträgen für TI-Messenger Provider. 

Diese REST Schnittstelle wird hier definiert: https://github.com/gematik/api-vzd/ unter src/openapi/I_VZD_TIM_Provider_Services.yaml

Die REST-Schnittstelle /owner ermöglich die Anpassung der Einträge durch Identitätseigentümer zzgl. Autoritativer Daten der Kartenherausgeber.

Genutzt werden die Standard FHIR Operationen https://build.fhir.org/http.html mit der Einschränkung auf eigene Resourcen und die autoritativen Daten der Kartenherausgeber.

Zur Nutzung dieser Operation muss ein entsprechendes owner-access_token vom FHIRDirectoryAuthorizationService vorliegen.

Ermöglicht Authentisierung und Autorisierung der TI-Anbieter zum Zugriff auf FHIR Directory. Am Anfang nur TI-Messenger Anbieter, später auch KIM-Anbieter und zukünftige Anbieter.

Bei Aufruf der REST-Schnittstelle /tim-provider-services wird ein Accesstoken (provider-accesstoken) benötigt. Hierfür muss sich der Client bei dem ProviderAuthorizationService des VZD-FHIR-Directory mittels OAuth2 Client Credentials Flow authentisieren. Zuvor MUSS der Client beim VZD-Anbieter Client-Credentials beantragen.

Geplante FHIR-Directory Schnittstellen in zukünftigen Releases:

Geplante Schnittstelle für die Administration der Daten im FHIR Verzeichnisdienst als Nachfolger für REST Pflegeschnittstelle (DirectoryAdministration).

Geplante Schnittstelle zum Auslesen größerer Datenmengen aus dem FHIR Verzeichnisdienst.

4.1 FHIR-Directory

Das FHIR-Directory ist eine Implementierung der HL7-FHIR-Spezifikation Release 4.0.1 (https://www.hl7.org/fhir/http.html).

Das FHIR-Directory ist nur über den FHIR-Proxy erreichbar.

4.1.1 Datenmodell

Es werden die FHIR-Ressourcen gemäß folgender Tabelle verwendet.

Alle Änderungen und Erweiterungen der FHIR Ressourcen sind in https://simplifier.net/vzd-fhir-directory veröffentlicht.

Tabelle 3: VZD-FHIR-Directory, FHIR-Ressourcen

FHIR-Ressource Beschreibung
Organization in gematik Directory (OrganizationDirectory) Profil der Organization Ressource.
(https://simplifier.net/vzd-fhir-directory/organizationdirectory)
Das Element Identifier wurde so geändert, dass Telematik-IDs als Identifier verwendet werden können.
Im Element type wird der Typ der Organisation eingetragen. Dafür werden die CodeSysteme https://simplifier.net/vzd-fhir-directory/organizationprofessionoid   und https://simplifier.net/vzd-fhir-directory/practitionerprofessionoid  sowie das ValueSet https://simplifier.net/vzd-fhir-directory/organizationtypevs  verwendet.
Practitioner in gematik Directory (PractitionerDirectory) Profil der Practitioner Ressource. Lediglich das Element Identifier wurde so geändert, dass Telematik-IDs als Identifier verwendet werden können. (https://simplifier.net/vzd-fhir-directory/practitionerdirectory)
Endpoint in gematik Directory (EndpointDirectory) Endpoint Ressource (https://simplifier.net/vzd-fhir-directory/endpointdirectory)
Location in gematik Directory (LocationDirectory) Location (https://simplifier.net/vzd-fhir-directory/locationdirectory)
HealthcareService in gematik Directory (HealthcareServiceDirectory) HealthcareService (https://simplifier.net/vzd-fhir-directory/healthcareservicedirectory)
PractitionerRole in gematik Directory (PractitionerRoleDirectory) PractitionerRole (https://simplifier.net/vzd-fhir-directory/practitionerroledirectory)

ML-123880 - Einschränkung der nutzbaren FHIR-Ressourcen (VZD-FHIR-Directory)

Nur die in Tabelle "VZD-FHIR-Directory, FHIR-Ressourcen" angegebenen Ressourcen dürfen im VZD-FHIR-Directory erzeugt werden. [<=]

4.1.2 Mapping von LDAP auf FHIR-Ressourcen

Die OrganizationDirectory- und PractitionerDirectory-Basiseinträge werden durch den FHIR Proxy mit den Daten aus dem VZD-LDAP-Directory initial erzeugt und anschließend fortlaufend aktualisiert. Die synchronisierten Daten können nicht durch die Besitzer (Leistungserbringer und Organisationen) geändert werden.

Die Daten aus dem VZD-LDAP-Directory werden wie folgt den FHIR-Ressourcen zugeordnet: https://github.com/gematik/api-vzd/blob/master/docs/LDAP2FHIR_Sync.adoc.

Zu jedem LDAP-VZD-SMC-B-Eintrag werden im FHIR VZD je eine Instanz der Ressourcen "Organization", "HealthcareService" und "Location" erzeugt bzw. aktualisiert.

Zu jedem LDAP-VZD-HBA-Eintrag werden im FHIR VZD je eine Instanz der Ressourcen "Practitioner", "PractitionerRole" und "Location" erzeugt bzw. aktualisiert.

Berücksichtigung der Zertifikate im LDAP VZD

Der Status von LDAP- und FHIR-VZD-Einträgen wird über das "active" Attribut des LDAP-Basiseintrags, der FHIR Organization Ressource und der FHIR Practitioner Ressource abgebildet. Das "active" Attribut des LDAP-Basiseintrags wird auf die "active" Attribute der FHIR Ressourcen gemappt.

Im LDAP VZD werden VZD-Einträge nicht gefunden, wenn keine gültigen Zertifikate für sie im LDAP VZD vorhanden sind. Diesem Mechanismus wird oft vertraut und der VZD-Eintrag am Ende seiner Laufzeit (bzw. am Ende der Laufzeit seiner Zertifikate) nicht über das "active" Attribut des LDAP-Basiseintrags gesperrt. Im FHIR VZD sind diese VZD-Einträge aktuell aktiv ("active" Attribut der FHIR Ressourcen) und können genutzt werden. Da dies zu Problemen führt (z.B. Zuweisung von eRezepten, die dann nicht abgerufen werden können), wird das Mapping vom LDAP VZD in den FHIR VZD erweitert.

Das Mapping der LDAP-Einträge in die FHIR-Einträge berücksichtigt die Zertifikate im LDAP VZD wie folgt:

4.1.3 FHIR RESTful API

Die Operationen der FHIR-Schnittstelle sind durch die FHIR-Spezifikation festgelegt (https://www.hl7.org/fhir/http.html).

Die Anzahl der mittels /search und /fdv/search Operation gefundenen und zurückgegebenen Einträge wird initial auf 100 begrenzt. Dieser Wert MUSS durch den FHIR VZD Anbieter konfigurierbar sein. Die zurückgegebenen Einträge werden in einem FHIR-Ressource-Bundle zusammengefasst. Im Attribut Bundle.total MUSS die Gesamtanzahl der Einträge im Bundle zurückgegeben werden. Für die Ermittlung der Gesamtzahl der gefundenen Einträge kann die Suchoperation _summary=count (https://hl7.org/fhir/search.html#summary) genutzt werden. Das Suchergebnis enthält dann in Bundle.total die Gesamtzahl der gefundenen Einträge, aber nicht die Einträge selbst.

Mit Angabe des Parameters _total=accurate (https://www.hl7.org/fhir/search.html#_total ) in der Suchoperation enthält das Suchergebnis die gefundenen Einträge (maximal 100) und in Attribut Bundle.total die gesamte Anzahl der Suchergebnisse im FHIR VZD (ohne Einschränkung auf 100 Ergebnisse).

Bei Verwendung von Parameter _total=accurate bitte beachten, dass die Suche mit diesem Suchparameter für den FHIR VZD performance-intensiver ist, da er die akkurate Gesamtanzahl ermitteln muss. Dieser Parameter darf deshalb durch den Client nur benutzt werden, wenn er diese Anzahl benötigt. 

4.1.4 Verlinkung von Personen und Organisationen in FHIR

Im FHIR VZD kann die Zugehörigkeit von Personen (Practitioner) zu Organisationen (Organization) hinterlegt werden. Das Eintragen dieser Verlinkung erfolgt im beidseitigen Einverständnis zwischen Organisation und Leistungserbringern.

Die Verlinkungsanfragen und Bestätigungen werden nicht in FHIR Daten abgelegt, sondern separat abgelegt. Erst mit Erteilung des beidseitigen Einverständnisses wird die Verlinkung in die FHIR Daten eingetragen.

Für das Eintragen der Verlinkungsdaten muss sich der Nutzer authentisieren. Die Authentisierung erfolgt je Rolle über folgende Authentisierungstoken.

  1. Leistungserbringer
    1. Ein Leistungserbringer authentisiert sich über das Owner-Authenticate-Verfahren (mit IDP-Dienst).
    2. Dabei erhält dieser einen Owner-Authenticate-Token, welcher an der administrativen Schnittstelle genutzt werden kann.
  3. Verantwortlicher einer Institution (Organisation)
    1. Der Verantwortliche authentisiert sich über das Owner-Authenticate-Verfahren (vereinfachtes Verfahren SMC-B oder IDP-Dienst-Verfahren).
    2. Dabei erhält dieser einen Owner-Authenticate-Token, welcher an der administrativen Schnittstelle genutzt werden kann.
  5. Kartenherausgeber (Holder)
    1. Ein Kartenherausgeber authentisiert sich über die neue Schnittstelle Holder-Authenticate.
    2. Hierzu verwendet er den bereits bekannten Keycloak, um sich ein entsprechenden Keycloak-IdToken per Client-Secret-Verfahren zu holen.
    3. Im Anschluss tauscht er diesen Token gegen einen Holder-AccessToken aus, welcher an der administrativen Schnittstelle genutzt werden kann.

Akzeptanzkriterien

ML-143700 - VZD-FHIR-Directory - Sichtbare Verbindung zwischen Personen und Organisationen

Für FHIR VZD Nutzer muss die Zugehörigkeit von Personen (Practitioner) zu Organisationen (Organization) sichtbar sein. Die Zugehörigkeit darf erst nach beidseitiger Bestätigung (von Person und Organisation) sichtbar sein. [<=]

ML-143701 - VZD-FHIR-Directory - Genehmigungspflichtige Verbindung zwischen Personen und Organisationen

Die Verbindung zwischen Personen und Organisationen muss beidseitig von den verlinkten Personen und Organisationen bestätigt werden.  [<=]

ML-143703 - VZD-FHIR-Directory - Dokumentation der Verlinkungs-Genehmigungen zwischen Personen und Organisationen

Die Genehmigungen, Ablehnungen und Löschungen der Verbindung zwischen Personen und Organisationen müssen dokumentiert werden und - durch die beteiligte Person und Organisation - einsehbar sein.  [<=]

ML-143702 - VZD-FHIR-Directory - Widerruf der Verbindung zwischen Personen und Organisationen

Die Widerrufung der Verbindung zwischen Personen und Organisationen muss einseitig möglich sein

[<=]

ML-143800 - VZD-FHIR-Directory - Authentisierung für Verlinkung zwischen Personen und Organisationen

Der FHIR VZD muss die Nutzer vor dem Eintragen von Verlinkungsdaten entsprechend ihrer Nutzergruppe authentisieren. Folgende Nutzergruppen müssen berücksichtigt werden

[<=]

ML-143878 - VZD-FHIR-Directory - Verbieten von Ressourcen-Verlinkungen ohne Verknüpfungsauftrag

Der FHIR VZD muss das direkte Eintragen der Verbindung zwischen Personen und Organisationen über die FHIR VZD Owner Schnittstelle verhindern. Das Eintragen dieser Verbindung ist nur im beidseitiges Einverständnis zwischen Organisation und Leistungserbringern erlaubt. [<=]

4.2 FHIR-Proxy

4.2.1 Schnittstellen

Alle Verbindungen des FHIR-Proxy sind TLS-verschlüsselt. Der Proxy weist sich gegenüber den Clients aus. Für den Zugriff der Clients auf den FHIR-VZD werden signierte Access-Tokens vergeben.

4.2.1.1 TLS-Verbindungsaufbau

Der FHIR-Proxy MUSS sich beim TLS-Verbindungsaufbau an den Endpunkten gegenüber Clients mit einem Extended Validation TLS-Zertifikat eines Herausgebers gemäß [CAB-Forum] authentisieren. Das Zertifikat MUSS an die Schnittstelle des Eingangspunkts für Clientsysteme gebunden werden, damit Clientsysteme beim TLS-Verbindungsaufbau eine vereinfachte Zertifikatsprüfung mit TLS-Standardbibliotheken durchführen können.

4.2.1.2 FHIR Schnittstelle für TI-Messenger-Nutzer FHIRDirectorySearchAPI

Endpunkte für die Suche von Einträgen im VZD-FHIR-Directory durch TI-Messenger-Clients

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/search   

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/search  

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/search 

Authentisierung

Um die Schnittstelle nutzen zu können, MÜSSEN sich die Clients mit einem gültigen Token authentisieren, das von einem Matrix-Homeserver aus der TI-Messenger-Föderation ausgestellt wurde. Im Folgenden werden diese Accesstoken Matrix-OpenID-Token genannt. Nach erfolgreicher Prüfung des Matrix-OpenID-Token stellt der FHIR-Proxy dem TI-Messenger-Client ein neues OAuth Accesstoken aus (search-access_token), das für Suchanfragen des TI-Messenger-Clients verwendet wird.

Das search-access_token enthält folgende Attribute:

{
  "iss": "https://fhir-directory.vzd.ti-dienste.de/tim-authenticate",
  "aud": "https://fhir-directory.vzd.ti-dienste.de/search",
  "exp": 1726648516,
  "scope": [ "search:read certificate:read” ],
  "iat": 1726562116
}

Das Attribut "iss" enthält die URL des Endpunktes für die Authentisierung in der jeweiligen Umgebung RU, TU oder PU.

Das Attribut "aud" enthält die URL des Endpunktes in der jeweiligen Umgebung RU, TU oder PU.

Die zeitliche Gültigkeit des search-access_tokens beträgt 24 Stunden.

Endpunkte für die Authentisierung

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/tim-authenticate   

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/tim-authenticate 

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/tim-authenticate 

Operationen

Die FHIR-Operationen für die Suche nach Einträgen im VZD-FHIR-Directory sind in der HL7-FHIR-Spezifikation (https://www.hl7.org/fhir/http.html ) festgelegt.

Zusätzlich zur HL7-FHIR-Spezifikation muss der FHIR VZD folgende Suchparameter unterstützen:

4.2.1.3 FHIR-Schnittstelle für Besitzer FHIRDirectoryOwnerAPI

Die Schnittstelle ermöglicht es den Besitzern einer Telematik-ID, ihren Eintrag im VZD-FHIR-Directory zu ändern. Im bei der Authentifizierung verwendeten Accesstoken ist die Telematik-ID des Nutzers enthalten. Nur der Eintrag (PractitionerDirectory oder OrganizationDirectory) mit der eigenen Telematik-ID darf verändert werden. Dabei dürfen nur die Attribute verändert werden, die nicht vom VZD-LDAP-Directory synchronisiert werden.

Endpunkte für das Ändern von eigenen Einträgen im VZD-FHIR-Directory durch TI-Messenger Clients und Org-Admin-Clients

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/owner  

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/owner 

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/owner 

Authentisierung

Um die Schnittstelle nutzen zu können, MÜSSEN sich die Clients mit einem gültigen Accesstoken authentisieren, das vom FHIR-Proxy ausgestellt wurde. Wenn kein gültiges Accesstoken im Client vorhanden ist, dann muss sich der Client an einem IDP der TI-IDP-Föderation authentisieren.

Nur der eigene Eintrag mit einem Identifier passend zur Telematik-ID aus dem Accesstoken KANN bearbeitet werden. Für einen eigenen OrganizationDirectory-Eintrag KÖNNEN weitere HealthcareService-Einträge erstellt und mit dem eigenen OrganizationDirectory-Eintrag verlinkt werden.

Das Accesstoken enthält folgende Attribute:

{
  "iss": "https://vzd-fhir-directory.vzd.ti-dienste.de/owner-authenticate",
  "sub": "<telematikID>",
  "aud": [ "https://vzd-fhir-directory.vzd.ti-dienste.de/owner", "https://fhir-directory.vzd.ti-dienste.de/search" ],
  "iat": 1630306800,
  "exp": 1630393200
  "Scope": "search:read owner:write certificate:read"
}

Das Attribut "iss" enthält die URL des Endpunktes für die Authentisierung in der jeweiligen Umgebung RU, TU oder PU.

Das Attribut "aud" enthält die URL des Endpunktes in der jeweiligen Umgebung RU, TU oder PU.

Die zeitliche Gültigkeit des Owner Accesstokens beträgt 24 Stunden.

Das Holder-Access-Token enthält folgende Attribute:

{
  "iss": "https://fhir-directory.vzd.ti-dienste.de/holder-authenticate",
  "clientId": "<ClientID die im KeyCloak für den Holder vergeben wurde>",
  "aud": [ "https://vzd-fhir-directory.vzd.ti-dienste.de/owner", "https://fhir-directory.vzd.ti-dienste.de/search" ],
  "iat": 1630306800,
  "exp": 1630393200
  "Scope": "search:read, owner:read, certificate:read"
}

Das Attribut "iss" enthält die URL des Endpunktes für die Authentisierung in der jeweiligen Umgebung RU, TU oder PU.

Das Attribut "aud" enthält die URL des Endpunktes in der jeweiligen Umgebung RU, TU oder PU.

Die zeitliche Gültigkeit des Holder-Access-Tokens beträgt 24 Stunden.

Das Attribut "Scope" enthält die Rechte, zukünftig auch owner:write.

Endpunkte für die Authentisierung

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/owner-authenticate  

In der Referenzumgebung (RU) ist die URL: https://vzd-fhir-directory-ref.vzd.ti-dienste.de/owner-authenticate   

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/owner-authenticate  

FHIR VZD Endpunkte für die Authentisierung mit dem SmartcardIDP

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/signin-gematik-idp-dienst 

In der Referenzumgebung (RU) ist die URL: https://vzd-fhir-directory-ref.vzd.ti-dienste.de/signin-gematik-idp-dienst  

In der Testumgebung (TU) ist die URL: https://vzd-fhir-directory-test.vzd.ti-dienste.de/signin-gematik-idp-dienst   

FHIR-VZD-Endpunkte für die Authentisierung mit dem gematik Authenticator und Polling Endpunkt

In der Produktionsumgebung (PU) sind die URLs:

In der Referenzumgebung (RU) sind die URLs: 

In der Testumgebung (TU) sind die URLs:

FHIR-VZD-Endpunkte für die Holder Authentisierung

Operationen

Die FHIR-Operationen für das Ändern von eigenen Einträgen im VZD-FHIR-Directory sind in der HL7-FHIR-Spezifikation (https://www.hl7.org/fhir/http.html ) festgelegt.

Daten

Das VZD-FHIR-Directory Datenmodell wird in Simplifier beschrieben [Simplifier-FHIR-VZD].

Für TI-Anwendungen werden die Kommunikationsadressen in den FHIR Endpoint eingetragen:

Tabelle 4: Tab_VZD_TI-Anwendungen_Endpoint

TI- Anwendung Endpoint.connectionType code Endpoint.address
TI Messenger tim Format (MXID in URL Form) für User entsprechend [matrix-uri-scheme]: 
                  matrix:u/localpart:domainpart

Beispiel MatrixID: 
@1-1tst-auto-ts-ow2:tim.test.gematik.de
MatrixID im URL Format in Endpoint.address: 
matrix:u/1-1tst-auto-ts-ow2:tim.test.gematik.de
4.2.1.4 Schnittstelle FHIRDirectoryTIMProviderAPI (I_VZD_TIM_Provider_Services.yaml)

Endpunkte

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/tim-provider-services 

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/tim-provider-services 

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/tim-provider-services 

Authentisierung

Um die Schnittstelle nutzen zu können, muss sich der Registrierungsdienst des TI-Messenger-Anbieters zuerst mit einem ti-provider-accesstoken authentisieren, das vom TI-Provider OAuth-Server des VZD-Anbieters ausgestellt wurde. Das ti-provider-accesstoken hat eine Gültigkeitsdauer von 5 Minuten. Dieses tauscht er bei dem VZD-FHIR-Directory Auth-Service gegen ein provider-accesstoken, das zur Authentifizierung an der Schnittstelle genutzt wird. 

Das provider-accesstoken enthält folgende Attribute:

{
  "iss": "https://fhir-directory.vzd.ti-dienste.de/ti-provider-authenticate",
  "sub": "<client_id>",
  "aud": [ "https://fhir-directory.vzd.ti-dienste.de/tim-provider-services" ],
  "iat": 1630306800,
  "exp": 1630308600,
  "clientId": "<client_id>"
}

Das Attribut "iss" enthält die URL des Endpunktes für die Authentisierung in der jeweiligen Umgebung RU, TU oder PU.

Das Attribut "aud" enthält die URL des Endpunktes in der jeweiligen Umgebung RU, TU oder PU.

Die zeitliche Gültigkeit des provider-accesstokens beträgt 24 Stunden. 

Endpunkte für die Authentisierung am VZD-FHIR-Directory Auth-Service

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/ti-provider-authenticate
In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/ti-provider-authenticate
In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/ti-provider-authenticate

Endpunkte um mit Client Credentials ein Token zu erhalten, das am Endpunkt ti-provider-authenticate eingetauscht werden kann

In der Referenzumgebung (RU) ist die URL:

 https://auth-ref.vzd.ti-dienste.de:9443/auth/realms/TI-Provider/protocol/openid-connect/token 

In der Testumgebung (TU) ist die URL:

 https://auth-test.vzd.ti-dienste.de:9443/auth/realms/TI-Provider/protocol/openid-connect/token 

In der Produktionsumgebung (PU) ist die URL:

 https://auth.vzd.ti-dienste.de:9443/auth/realms/TI-Provider/protocol/openid-connect/token  

Registrierung

Für den Zugriff auf den TI-Provider OAuth-Server MUSS der TI-Messenger-Anbieter für seinen Registrierungsdienst beim VZD-Anbieter Client-Credentials beantragen. Die Beantragung erfolgt über einen genehmigungspflichtigen Service-Request im TI-ITSM-System.

Die Registrierung und Vergabe der Credentials erfolgt dabei auf Anbieterebene.

Der Antrag MUSS folgende Informationen enthalten, um weiter bearbeitet werden zu können:

Nach Prüfung der Angaben, werden die Zugangsdaten direkt vom Anbieter Zentrale Plattformdienste (vgl. gemKPT_Betr) an die gewünschte E-Mail-Adresse übermittelt.

Es ist zu beachten, dass dieser Prozess ausschließlich für Neuanlagen und Löschungen vorgesehen ist. Änderungen oder der Neuversand von Zugangsdaten können nicht bearbeitet werden.

Operationen

Die Schnittstelle ist in I_VZD_TIM_Provider_Services.yaml als OpenAPI RESTful Service spezifiziert.

https://github.com/gematik/api-vzd/blob/main/src/openapi/I_VZD_TIM_Provider_Services.yaml 

Tabelle 5: Tab_VZD_TIM-Provider-Services_Operations

Operation Beschreibung
GET /
"getInfo"		 Mit dieser Operation können Metadaten (insbesondere auch die Version und das verwendete yaml-File) dieser Schnittstelle abgefragt werden.
GET /FederationList/federationList.jws Mit dieser Operation wird die Liste der an der TI-Messenger-Föderation beteiligten Matrix-Domainnamen abgefragt (Föderationsliste). 
GET /localization
"whereIs"		 Gibt für die übergebene MXID den Teil des Directories zurück, in dem die MXID enthalten ist.
POST /federation
"addTiMessengerDomain"		 Eine Domaine zur Föderation hinzufügen.
GET /federation
"getTiMessengerDomain"		 Lesen einer oder aller eigener Domains.
PUT /federation
"updateTiMessengerDomain"		 Aktualisierung einer Domaine.
DELETE /federation
"deleteTiMessengerDomain"		 Löschen einer Domaine.
GET /federationCheck
"checkTiMessengerDomains"		 Prüft, ob alle eigenen Domains (durch Token ermittelbar) zu aktiven Organisationen gehören. Gibt die eigenen Domains zurück, die zu inaktiven Organisationen gehören.

Im Attribut "sub" des Accesstokens ist die client_id des TI-Messenger-Registrierungsdienstes enthalten.

Bei Hinzufügen einer Domain zur Föderation (addTiMessengerDomain) MUSS der FHIR VZD prüfen, ob für die dazugehörende telematikID eine aktive Organisation vorliegt.

4.2.1.5 FHIR Schnittstelle für Versicherte FHIRDirectoryFdvSearchAPI

Endpunkte für die Suche von Einträgen im VZD-FHIR-Directory durch Versicherte

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/fdv/search    

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/fdv/search  

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/fdv/search 

Authentisierung

Um die Schnittstelle nutzen zu können, MÜSSEN sich die Clients mit einem gültigen search-access_token authentisieren, das vom FHIR-Directory Auth-Service ausgestellt wurde. Das search-access_token erhalten Fachdienste nach Authentisierung am FHIR-OAuth-Server /token Endpunkt im Austausch gegen das service-authz-token und TIM-Clients von Versicherten nach Authentisierung am Matrix-Homeserver im Austausch gegen das Matrix-OpenID-Token.

Das search-access_token (Fachdienste) enthält folgende Attribute:

{
  "scope": "fdv_search:read certificate:read",
  "iss": "https://fhir-directory.vzd.ti-dienste.de/service-authenticate",
  "aud": "https://fhir-directory.vzd.ti-dienste.de/fdv/search",
  "iat": 1726556719,
  "exp": 1726643119
}

Das search-access_token (TIM-Clients von Versicherten) enthält folgende Attribute:

{
  "iss": "https://fhir-directory.vzd.ti-dienste.de/tim-authenticate",
  "aud": [ "https://fhir-directory.vzd.ti-dienste.de/fdv/search" ],
  "iat": 1630306800,
  "exp": 1630393200,
  "scope": "fdv_search:read certificate:read"
}

Das Attribut "iss" enthält die URL des Endpunktes für die Authentisierung in der jeweiligen Umgebung RU, TU oder PU.

Das Attribut "aud" enthält die URL des Endpunktes in der jeweiligen Umgebung RU, TU oder PU.

Die zeitliche Gültigkeit des search-access_tokens beträgt 24 Stunden.

Endpunkte um mit Client Credentials ein Token zu erhalten, das am Endpunkt service-authenticate eingetauscht werden kann

In der Referenzumgebung (RU) ist die URL:

 https://auth-ref.vzd.ti-dienste.de:9443/auth/realms/Service-Authenticate/protocol/openid-connect/token  

In der Testumgebung (TU) ist die URL:

 https://auth-test.vzd.ti-dienste.de:9443/auth/realms/Service-Authenticate/protocol/openid-connect/token 

In der Produktionsumgebung (PU) ist die URL:

 https://auth.vzd.ti-dienste.de:9443/auth/realms/Service-Authenticate/protocol/openid-connect/token   

Endpunkte für die Authentisierung (Fachdienste)

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/service-authenticate 

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/service-authenticate 

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/service-authenticate 

Endpunkte für die Authentisierung (TIM-Clients von Versicherten)

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/tim-authenticate   

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/tim-authenticate 

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/tim-authenticate 

Operationen

Die FHIR-Operationen für die Suche nach Einträgen im VZD-FHIR-Directory sind in der HL7-FHIR-Spezifikation (https://www.hl7.org/fhir/http.html ) festgelegt.

Zusätzlich zur HL7-FHIR-Spezifikation muss der FHIR VZD folgende Suchparameter unterstützen:

Falls der Versicherte im Rahmen einer Anwendung nur eine Teilmenge aus dem VZD-FHIR-Directory sehen soll (z.B. nur Apotheken oder nur bestimmte Organisationen), muss das durch den Client durch eine geeignete Suche sichergestellt werden.

Sichtbarkeit von FHIR-Ressourcen

Die Sichtbarkeit von definierten FHIR-Ressourcen kann vom Eigentümer (Owner) des FHIR-VZD-Eintrags eingeschränkt werden. Folgende Einschränkungen der Sichtbarkeit sind möglich:

FHIR-Ressourcen mit eingeschränkter Sichtbarkeit werden an Schnittstelle FHIRDirectoryFdvSearchAPI (/fdv/search) durch den FHIR VZD aus dem Suchergebnis entfernt. Bei der FHIR-Ressource "Organization" werden auch alle verlinkten FHIR-Ressourcen aus dem Suchergebnis entfernt.

Die Sichtbarkeit seiner FHIR-Ressourcen kann der Eigentümer (Owner) über die Schnittstelle für Besitzer FHIRDirectoryOwnerAPI (/owner) verwalten.

4.2.1.6 Schnittstelle zum Lesen von Zertifikaten von Verzeichniseinträgen I_FHIR_VZD_Certificates

Endpunkte zum Lesen von Zertifikaten von Verzeichniseinträgen (read_FhirVZD_Certificates)

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/certificates/Certificates  

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/certificates/Certificates  

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/certificates/Certificates  

Abfrageschnittstelle Zertifikat-Version (getInfo)

In der Produktionsumgebung (PU) ist die URL: https://fhir-directory.vzd.ti-dienste.de/certificates/

In der Referenzumgebung (RU) ist die URL: https://fhir-directory-ref.vzd.ti-dienste.de/certificates/

In der Testumgebung (TU) ist die URL: https://fhir-directory-tu.vzd.ti-dienste.de/certificates/

Authentisierung

Um die Schnittstelle nutzen zu können, MÜSSEN sich die Clients mit einem gültigen Token authentisieren, das vom FHIR-Directory Auth-Service ausgestellt wurde. Akzeptiert werden die folgenden Token:

Operationen

Die Schnittstelle ist in I_FHIR_VZD_Certificates.yaml als OpenAPI RESTful Service spezifiziert.

https://github.com/gematik/api-vzd/blob/main/src/openapi/I_FHIR_VZD_Certificates.yaml 

Tabelle 6: Tab_I_FHIR_VZD_Certificates_Operations

Operation Beschreibung
GET /
"getInfo"		 Mit dieser Operation können Metadaten (insbesondere auch die Version und das verwendete yaml-File) dieser Schnittstelle abgefragt werden.
GET /Certificates
"read_FhirVZD_Certificates"		 Mit dieser Operation werden die Zertifikate vom FHIR VZD abgefragt. 

Akzeptanzkriterien

ML-161973 - VZD-FHIR-Directory - I_FHIR_VZD_Certificates Authentisierung

Der FHIR VZD muss bei der Authentisierung für Schnittstelle I_FHIR_VZD_Certificates das übergebene Token auf Gültigkeit und den enthaltenen Scope “certificate:read” prüfen. [<=]

ML-161974 - VZD-FHIR-Directory - I_FHIR_VZD_Certificates leeres Abfrageergebnis

Wenn für die Abfrage von Zertifikaten über Schnittstelle I_FHIR_VZD_Certificates keine Treffer gefunden werden, muss der FHIR VZD ein leeres Ergebnis liefern. [<=]

ML-161981 - VZD-FHIR-Directory - I_FHIR_VZD_Certificates Performance

Der FHIR VZD muss die Abfrage von Zertifikaten über Schnittstelle I_FHIR_VZD_Certificates performant bereitstellen (z.B. über eine performance-optimierte Datenbank). [<=]

4.2.2 Aktualisierung der Basiseinträge

Der FHIR-Proxy aktualisiert regelmäßig die Basiseinträge im VZD-FHIR-Directory mit den geänderten Daten des VZD-LDAP-Directories (siehe AF_10047 Einträge mit dem VZD-LDAP-Directory abgleichen). Das Intervall für die regelmäßige Aktualisierung MUSS konfigurierbar sein und wird initial auf 2 Stunden festgelegt. 

Es MUSS (analog dem Background-Sync-Verfahren in die LDAP flache Liste) eine weitere Synchronisation mittels PUSH in den FHIR VZD möglich sein.

Zukünftig ist vorgesehen, dass Kartenherausgeber direkt die Basiseinträge ihrer Mitglieder im VZD-FHIR-Directory über eine FHIR-Schnittstelle verwalten können.

4.2.3 Erzeugung und Bereitstellung der Föderationsliste

Die Föderationsliste MUSS bei Änderung der Domains und/oder telematikIDs durch TI-Messenger-Anbieter neu erzeugt und zum Download über die Schnittstelle I_VZD_TIM_Provider_Services bereitgestellt werden.

Die Föderationsliste hat folgende Struktur:

{
   "version": <Version der Föderationsliste (Integer)>,
    "domainList": [
    {
      "domain": "Domain",
      "telematikID": "Telematik-ID der Organisation, welche die Domain nutzt",
      "isInsurance": true,
      "ik": [108433248, 104127692],
     "timAnbieter": "Zuweisungsgruppe im TI-ITSM-System vom TI-Messenger Anbieter,
                               der die Domain angelegt hat",
      "redirectDomains": [ domain1.fr, domain7.de ] "Zu berücksichtigende redirect-Domains,
                                                                                  verarbeitet durch den proxy-Server"
    }
  ]
}

Zu Domänen, die Accounts von Versicherten bereitstellen (isInsurance: true) MUSS mindestens ein Institutionskennzeichen (IK) eingetragen werden. Bei Einträgen mit dem Wert (isInsurence:false) DARF kein IK hinterlegt werden. Ein IK DARF in der gesamten Föderationsliste nur einmal enthalten sein.

Das VZD-FHIR-Directory MUSS für das Format des IK sicherstellen:

Das Institutionskennzeichen MUSS aus einer neunstelligen Ziffernfolge bestehen, deren erste 2 Stellen (Klassifikation für Krankenversicherungsträger) einem Wert aus einer konfigurierbaren Liste entsprechen muss. Initial enthält diese konfigurierbare Liste die Werte

Beim Hinterlegen von Institutionskennzeichen MÜSSEN diese - entsprechend [GR-IK-2023-11] Kapitel 1.2.5 - gegen die enthaltene Prüfziffer validiert werden und nur bei erfolgreicher Prüfung der Eintrag erstellt werden.

Der Wert für "timAnbieter" MUSS vom AZPD bei der Beantragung der Credentials des TI-Messenger Anbieters/-Herstellers erfasst und bei jeder Änderung der anderen Felder vom VZD-FHIR-Directory aktualisiert werden. Der Wert für "timAnbieter" DARF AUSSCHLIEßLICH durch den AZPD bzw. durch das VZD-FHIR-Directory geändert werden. Mit dieser Automatisierung sollen manuelle Fehler beim Setzen durch die Nutzer vermieden werden.

Die redirectDomains werden mit dem Förderationseintrag persistiert und vom Proxy freigeschaltet.
Ohne entsprechende Pflege von RedirectDomains ist der Aufruf entsprechender URLs bei der Matrix-Server-Discovery (z.B. bei einem Redirect) nicht möglich.

Die Föderationsliste MUSS mit einer JWS gemäß RFC7797 signiert werden. Der zu verwendende Signatur-Algorithmus MUSS "ES256" oder "BP256R1" sein. Der Signatur-Algorithmus wird vom Client - beim Abruf der Föderationsliste - über Parameter "sigAlg" gewählt. Für die Signatur MUSS ein Signatur-Zertifikat der Komponenten-PKI der TI (C.FD.SIG) verwendet werden. Das Signatur-Zertifikat MUSS im Signatur-Header enthalten sein.

Der Signatur-Header hat folgende Struktur:

{
  "typ":"JWT",
  "alg": "ES256",
  "x5c": [
    "<X.509 Sig-Cert, base64-encoded DER>"
  ]
}

Die signierte Föderationsliste hat gemäß RFC7797 folgende Struktur:

Signatur-Header.Föderationsliste.Signatur

{
  "payload": "<Föderationsliste, BASE64URL>",
  "signatures": [
    {
      "header":<Signatur-Header>,
      "signature":"<signature, BASE64URL>"
    }
  ]
}		 

  
Die einzelnen Bestandteile der signierten Föderationsliste sind Base64 kodiert.  

  

 Ein Beispiel für die Föderationsliste:   

  
eyJhbGciOiJCUDI1NlIxIiwieDVjIjpbIk1JSUMrVENDQXFDZ0F3SUJBZ0lDYkFZd0NnWUlLb1pJemowRUF3SXdnWVF4Q3pBSkJnTlZCQVlUQWtSRk1SOHdIUVlEVlFRS0RCWm5aVzFoZEdscklFZHRZa2dnVGs5VUxWWkJURWxFTVRJd01BWURWUVFMRENsTGIyMXdiMjVsYm5SbGJpMURRU0JrWlhJZ1ZHVnNaVzFoZEdscmFXNW1jbUZ6ZEhKMWEzUjFjakVnTUI0R0ExVUVBd3dYUjBWTkxrdFBUVkF0UTBFMU1DQlVSVk5VTFU5T1RGa3dIaGNOTWpNd01USTFNVEEwTXpVMldoY05Namd3TVRJME1UQTBNelUxV2pCek1Rc3dDUVlEVlFRR0V3SkVSVEV5TURBR0ExVUVDZ3dwWVhKMllYUnZJRk41YzNSbGJYTWdSMjFpU0NCVVJWTlVMVTlPVEZrZ0xTQk9UMVF0VmtGTVNVUXhFREFPQmdOVkJBVVRCekF3TURBeExVRXhIakFjQmdOVkJBTU1GVlphUkMxR1NFbFNMVVpNYVhOMExWTnBaMjVsY2pCYU1CUUdCeXFHU000OUFnRUdDU3NrQXdNQ0NBRUJCd05DQUFRWXRpc3hVUEpTdUMwdG85bE9zMXpkblJwZWJaMGljaGNnaTFzTnQ4YnVDMm5IVFBIQm5DVHJ3ZklNS1k5TEFSYU9zM05RQUlsM0xSM1podVRHcWM4bW80SUJEekNDQVFzd0hRWURWUjBPQkJZRUZKK20wTnh3RHc2L1BxRmw5NzlxdWMwYlA0YWJNQjhHQTFVZEl3UVlNQmFBRkRyaXFpV1NUcXlwbEgzUEdXbnFFd2E1cUREVE1FOEdDQ3NHQVFVRkJ3RUJCRU13UVRBL0JnZ3JCZ0VGQlFjd0FZWXphSFIwY0RvdkwyOWpjM0F5TFhSbGMzUnlaV1l1YTI5dGNDMWpZUzUwWld4bGJXRjBhV3N0ZEdWemRDOXZZM053TDJWak1BNEdBMVVkRHdFQi93UUVBd0lIZ0RBaEJnTlZIU0FFR2pBWU1Bb0dDQ3FDRkFCTUJJRWpNQW9HQ0NxQ0ZBQk1CSUZMTUF3R0ExVWRFd0VCL3dRQ01BQXdOd1lGS3lRSUF3TUVMakFzTUNvd0tEQW1NQ1F3Rmd3VVZtVnllbVZwWTJodWFYTmthV1Z1YzNRdFZFa3dDZ1lJS29JVUFFd0VnU3N3Q2dZSUtvWkl6ajBFQXdJRFJ3QXdSQUlnVDJCUmJDSUltT3BTVUgvNTB5U1EvQ1ppOEV6bEF4Qkg0RXJMdGxvWURHY0NJR1hjUjJZZzRocG9VS2U3cHFIamJQSGU5Y2liUjNHZGVtNG5uQ25NVHJ1ZSJdLCJ0eXAiOiJKV1QifQ.eyJ2ZXJzaW9uIjoxMjgyLCJkb21haW5MaXN0IjpbeyJkb21haW4iOiJkdW1teURvbWFpbiIsInRlbGVtYXRpa0lEIjoiMS0xZ2VtdGVzdC1vd25lci0wMDAxIiwidGltQW5iaWV0ZXIiOm51bGwsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiJEdW1teURvbWFpbjIiLCJ0ZWxlbWF0aWtJRCI6IjEtMWdlbXRlc3Qtb3duZXItMDAwMSIsInRpbUFuYmlldGVyIjpudWxsLCJpc0luc3VyYW5jZSI6ZmFsc2V9LHsiZG9tYWluIjoibWVzc2VuZ2VyLnNwaWxpa2luLmRldiIsInRlbGVtYXRpa0lEIjoiMS0yYXJ2dHN0LWFwMDAwMDAwIiwidGltQW5iaWV0ZXIiOm51bGwsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiJ0aS1tZXNzZW5nZXIuZG9tYWluIiwidGVsZW1hdGlrSUQiOiIxLTJhcnZ0c3QtYXAwMDAwOTQiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRpLW1lc3Nlbmdlci5nZG9tYWluIiwidGVsZW1hdGlrSUQiOiIxLTJhcnZ0c3QtYXAwMDAwOTQiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6IjI5ZGg5MmdzMzNqZDAxMC5sb2NhbGhvc3QiLCJ0ZWxlbWF0aWtJRCI6IjI5ZGg5MmdzMzNqZCIsInRpbUFuYmlldGVyIjoiT1JHLTAwMjI6QlQtMDE1MiIsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiIyNjE2YjNmMzczYjkwMDEudHUudGltcmVmLmFrcXVpbmV0Lm54Mi5kZXYiLCJ0ZWxlbWF0aWtJRCI6IjI2MTZiM2YzNzNiOSIsInRpbUFuYmlldGVyIjoiT1JHLTAwMjI6QlQtMDE1MiIsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiIyOWRoOTJnczMzamQwMDEudHUudGltcmVmLmFrcXVpbmV0Lm54Mi5kZXYiLCJ0ZWxlbWF0aWtJRCI6IjI5ZGg5MmdzMzNqZCIsInRpbUFuYmlldGVyIjoiT1JHLTAwMjI6QlQtMDE1MiIsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiIyOWRoOTJnczMzamQ1MGYudHUudGltcmVmLmFrcXVpbmV0Lm54Mi5kZXYiLCJ0ZWxlbWF0aWtJRCI6IjI5ZGg5MmdzMzNqZCIsInRpbUFuYmlldGVyIjoiT1JHLTAwMjI6QlQtMDE1MiIsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiJtc2dzcnYxLmRldi50aW1wbHVzLmFydmF0by1zeXN0ZW1zLmRlIiwidGVsZW1hdGlrSUQiOiIxMS1TTUMtQi1UZXN0a2FydGUtODgzMTEwMDAwMTM5ODU4IiwidGltQW5iaWV0ZXIiOm51bGwsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiJtYXRyaXguZGV2LnNlcnZpY2UtdGkuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMWdlbXRlc3Qtb3duZXItMDAwMSIsInRpbUFuYmlldGVyIjpudWxsLCJpc0luc3VyYW5jZSI6ZmFsc2V9LHsiZG9tYWluIjoidHAwNGEuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMjAwMTA1NDc0NjIiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDYuMDYuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMjAwMTAyODAwNDEiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6IjI5ZGg5MmdzMzNqZDAxMS5sb2NhbGhvc3QiLCJ0ZWxlbWF0aWtJRCI6IjI5ZGg5MmdzMzNqZCIsInRpbUFuYmlldGVyIjoiT1JHLTAwMjI6QlQtMDE1MiIsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiJ0cDA1LjAxLmZyIiwidGVsZW1hdGlrSUQiOiIxLTIwMDEwNjMyNTExIiwidGltQW5iaWV0ZXIiOm51bGwsImlzSW5zdXJhbmNlIjpmYWxzZX0seyJkb21haW4iOiJwZXJmb3JtYW5jZTU5LnRlc3QuYXJ2YXRvLmRlIiwidGVsZW1hdGlrSUQiOiIxLTIwNzIwMjQ4MDQ0IiwidGltQW5iaWV0ZXIiOm51bGwsImlzSW5zdXJhbmNlIjp0cnVlfSx7ImRvbWFpbiI6InBlcmZvcm1hbmNlMTAudGVzdC5hcnZhdG8uZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMjA3MjA1MTA1NDIiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDYuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMjAwMTA1MjM0NDIiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDdQYXJ0aWFsTmFtZS5kZSIsInRlbGVtYXRpa0lEIjoiMS0yMDQ3MDAxMjA4MyIsInRpbUFuYmlldGVyIjpudWxsLCJpc0luc3VyYW5jZSI6ZmFsc2V9LHsiZG9tYWluIjoidHAwNi0wMS5kZSIsInRlbGVtYXRpa0lEIjoiMS0yMDAxMDk4OTk4MyIsInRpbUFuYmlldGVyIjpudWxsLCJpc0luc3VyYW5jZSI6ZmFsc2V9LHsiZG9tYWluIjoidHAwNi0wMi5kZSIsInRlbGVtYXRpa0lEIjoiMS0yMDAxMDc2NzY1NiIsInRpbUFuYmlldGVyIjpudWxsLCJpc0luc3VyYW5jZSI6ZmFsc2V9LHsiZG9tYWluIjoidHAwNi0wMy5kZSIsInRlbGVtYXRpa0lEIjoiMS0yMDAxMDI4ODQ2NiIsInRpbUFuYmlldGVyIjpudWxsLCJpc0luc3VyYW5jZSI6ZmFsc2V9LHsiZG9tYWluIjoidHAwNi0wNC5kZSIsInRlbGVtYXRpa0lEIjoiMS0yMDAxMDYxOTM4OCIsInRpbUFuYmlldGVyIjpudWxsLCJpc0luc3VyYW5jZSI6ZmFsc2V9LHsiZG9tYWluIjoiYXJ2YXRvLnR1LnRpbXJlZi5ha3F1aW5ldC5ueDIuZGV2IiwidGVsZW1hdGlrSUQiOiIxLTJhcnZ0c3QtYXAwMDAwMDAiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDYuMDUuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMjAwMTA0NzM1NzYiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDcuMDMuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMjA0NzAyNzI3OTAiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDgtMDEuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMjA0NzA2MTQ1MjAiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDkuMDAuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMWFydnRzdC10ZXN0b3JnLXRwMDkuMDAiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDkuMDEuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMWFydnRzdC10ZXN0b3JnLXRwMDkuMDEiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRwMDkuMDIuZGUiLCJ0ZWxlbWF0aWtJRCI6IjEtMWFydnRzdC10ZXN0b3JnLXRwMDkuMDIiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfSx7ImRvbWFpbiI6InRpLW1lc3Nlbmdlci50ZXN0Mi5nZG9tYWluIiwidGVsZW1hdGlrSUQiOiIxLTJhcnZ0c3QtYXAwMDAwOTMiLCJ0aW1BbmJpZXRlciI6bnVsbCwiaXNJbnN1cmFuY2UiOmZhbHNlfV19.TLmI56NcYPyMT6DcS56RnCeuJ9NuCZfqmQhjmSoLm29V91ez-7uRuVcRHgu4tdLSk7Zldt-yM3MUST95CdMq3Q

  
4.2.4 Lokalisierung einer MXID (Operation whereIs)

  
Die Operation prüft, in welchem Teil des Directorys (Organisation, Person) eine MXID enthalten ist, und gibt das Prüfergebnis zurück. Übergeben wird die MXID an die Operation in URL Form.
 Damit diese Operation performant ist, darf bei Aufruf der Operation nicht der gesamte FHIR Datenbestand durchsucht werden. Dies kann z. B. durch eine Performance-optimierte Tabelle mit den MXIDs und dazugehörigem Ergebnis gewährleistet werden.

  
Die Authentisierung des Clients erfolgt für Operation whereIs entsprechend Kapitel 4.2.1.4 Schnittstelle FHIRDirectoryTIMProviderAPI.

  
Der FHIR-Proxy MUSS die Lokalisierung einer MXID über Operation whereIs performant bereitstellen. Dazu MUSS der FHIR-Proxy bei jeder Änderung an den Endpoint-Einträgen (der MXID darin) die benötigten Daten für die performante Antwort der whereIs Operation aktualisieren. Der FHIR-Proxy DARF NICHT die originalen FHIR-Daten für die Ausführung der whereIs Operation durchsuchen.

  
4.3 Übergreifende Vorgaben

  
4.3.1 Sicherheit und Datenschutz

  
Die folgenden Vorgaben gelten auch für den FHIR-VZD.

  

   
TIP1-A_5546-01 - VZD, Integritäts- u. Authentizitätsschutz

   
Der Anbieter des VZD MUSS die Integrität und Authentizität der im VZD gespeicherten Daten gemäß den Richtlinien des Bundesamtes für Sicherheit in der Informationstechnik für allgemeine Verzeichnisdienste, [BSI APP.2.1], implementieren. [<=]

  

  

   
TIP1-A_5548 - VZD, Protokollierung der Änderungsoperationen

   
Der VZD MUSS Änderungen der Verzeichnisdiensteinträge protokollieren und muss sie 6 Monate zur Verfügung halten. [<=]

  

  
6 Monate ist die maximale Nachweistiefe, ohne in den Bereich der Vorratsdatenspeicherung zu kommen.

  

   
TIP1-A_5549 - VZD, Keine Leseprofilbildung

   
Der VZD DARF Suchanfragen NICHT speichern oder protokollieren.
 [<=]

  

  

   
TIP1-A_5550 - VZD, Keine Kopien von gelöschten Daten

   
Der VZD DARF von gelöschten Daten KEINE Kopien speichern.
 [<=]

  

  

   
TIP1-A_5551 - VZD, Sicher gegen Datenverlust

   
Der Anbieter des VZD MUSS den Dienst gegen Datenverlust absichern.
 [<=]

  

  

   
TIP1-A_5552 - VZD, Begrenzung der Suchergebnisse

   
Der VZD MUSS die Ergebnisliste einer Suchanfrage auf 100 Suchergebnisse begrenzen.
 [<=]

  

  
Die 100 Suchergebnisse beziehen sich auf die FHIR-Ressourcen HealthcareService bzw. PractitionerRole. Alle referenzierten und durch Suchparameter "_include" einbezogenen Ressourcen werden bei der Begrenzung der Suchergebnisse nicht mitgezählt.

  
Das Bundle im FHIR-Suchergebnis MUSS immer zu jeder enthaltenen FHIR-Ressource HealthcareService bzw. PractitionerRole alle referenzierten und durch "_include" einbezogenen Ressourcen enthalten und damit ein vollständiges Paket der enthaltenen Ressourcen darstellen.

  

   
TIP1-A_5553 - VZD, Private Schlüssel sicher speichern

   
Der VZD MUSS seine privaten Schlüssel sicher speichern und ihr Auslesen verhindern um Manipulationen zu verhindern.
 [<=]

  

  

   
TIP1-A_5554-01 - VZD, Registrierungsdaten sicher speichern

   
Der VZD MUSS die Integrität und Authentizität der gespeicherten Registrierungsdaten gewährleisten. [<=]

  

  

   
TIP1-A_5556 - VZD, Fehler Logging

   
Der VZD MUSS lokal und remote erkannte Fehler in seinem lokalen Speicher protokollieren.
 [<=]

  

  

   
TIP1-A_5558 - VZD, Sicheres Speichern der TSL

   
Der VZD MUSS  die Inhalte der TSL in einem lokalen Trust Store sicher speichern und für X.509-Zertifikatsprüfungen lokal zugreifbar halten.
 [<=]

  

  
Das X.509-Root-CA Zertifikat MUSS für Zertifikatsprüfungen im Truststore des FHIR VZD gespeichert sein.

  
Der FHIR VZD MUSS wöchentlich prüfen, ob neue X.509-Root-CA-Versionen existieren und Cross-Zertifikate verfügbar sind. Falls dies der Fall ist, so MUSS der FHIR VZD diese neuen Root-Versionen in seinen Truststore importieren.

  
Nach der Erzeugung einer neuen Root-Version der X.509-Root-CA der TI wird dessen selbstsigniertes Zertifikat und Cross-Zertifikate auf den Download-Punkt gemäß [ROOT-CA] abgelegt. Automatisiert kann der FHIR VZD von dort die Verfügbarkeit neuer Versionen überwachen. Zusätzlich kann der folgende Download-Punkt unter [ROOT-CA-JSON] verwendet werden. Dort werden die aktuellen Root-Zertifikate inkl. deren Cross-Zertifikate gepflegt. Im Regelfall wird alle zwei Jahre eine neue Root-Version erzeugt. Die Dateigröße der heruntergeladenen JSON-Datei kann man als Hashfunktion verwenden. Hiermit kann man beispielsweise mit Hilfe des Tools curl die HTTP-Methode HEAD verwenden und damit erfahren ob die lokale Kopie der JSON-Datei noch aktuell ist. Die JSON-Datei ist ein Array, in dem Associative Arrays als Elemente aufgeführt werden. Diese Elemente enthalten je ein Root-Zertifikat inkl. Cross-Zertifikate für das chronologisch vorhergehende und das nachfolgende Root-Zertifikat. D. h., kryptographisch gesehen stellt dies eine doppelt verkettete Liste dar.

  
Die Sub-CA Zertifikate werden auf dem Download-Punkt gemäß [Sub-CA] abgelegt.

  
4.3.2 Betrieb

  
In diesem Kapitel werden übergreifende, betriebliche Anforderungen getroffen oder auf Kapitel mit speziellen Ausprägungen für den Verzeichnisdienst FHIR Directory in normativen Querschnittsdokumenten verwiesen.

  
Die vollständige Auflistung aller Schnittstellen und Endpunkte finden sich in [gemKPT_Betr#5.3.2.26].

  
Die spezifischen Anforderungen zu Last und Performance finden sich in [gemSpec_Perf#3.24.1.3].

  
Die spezifischen Anforderungen zur Lieferung von Betriebsdaten finden sich in [gemSpec_Perf#3.24.2].

  
4.3.3 FHIR-Suchoptionen

  
Die Suche im FHIR VZD basiert auf den Standard-FHIR-Suchmöglichkeiten https://build.fhir.org/search.html.

  
In diesem Kapitel werden Suchoptionen mit besonderer Bedeutung für TI-Anwendungen beschrieben.

  
4.3.3.1 FHIR-Umkreissuche

  
Der FHIR VZD muss die Umkreissuche um eine bestimmte Geoposition unterstützen. Dafür muss die FHIR-Suche über den "near" Parameter für Location Ressourcen erlaubt werden https://www.hl7.org/fhir/location.html#8.7.6.1.1, https://build.fhir.org/location.html#search 

  
Der Client muss bei der Umkreissuche alle "near" Suchparameter obligatorisch angeben ([latitude]|[longitude]|[distance]|[units]).

  
5 Anwendungsfälle

  
5.1 TI-Messenger-Nutzer sucht Einträge im FHIR-Directory

  

   
AF_10036-02 - Nutzer sucht Einträge im FHIR-Directory

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Akteure 
        
        
     
         
  • Mitarbeiter im Gesundheitswesen
    •  
         
  • Versicherte
    •  
        
 		 
      
 
      
 
       Beschreibung 
       Nutzer können im FHIR-Directory über die Einstiegspunkte HealthcareServiceDirectory-, PractitionerRoleDirectory- und EndpointDirectory-Einträgen nach allen FHIR VZD Ressourcen suchen.
 
 Für die Suche von TI-Messenger Nutzern im FHIR-Directory ist eine Authentisierung am FHIR-Directory Auth-Service erforderlich. Hier ist die Authentisierung mit TI-Messenger-Clients beschrieben.
  
        
     
         
  1. Der TIM-Client des Nutzers prüft, ob er ein gültiges search-access_token vom FHIR VZD Auth-Service vorliegen hat. [1]
     
    2.  
         
  2. Wenn dem TIM-Client kein gültiges search-access_token vorliegt, fragt er bei seinem Matrix-Homeserver  ein Matrix-OpenID-Token ab. [2-4]
    3.  
         
  3. Abruf search-access_token [5-13]
     Der TIM-Client tauscht das Matrix-OpenID-Token gegen ein search-access_token ein. Der FHIR-Directory Auth-Service  
     
    4.  
         
       
          
    1. prüft ob das Matrix-OpenID-Token von einem Matrix-Homeserver aus der TI-Föderation stammt [6]
      2.  
          
    2. ermittelt den Port unter dem der Userinfo Endpunkt des Matrix-Homeservers zu erreichen ist [7]
      3.  
          
    3. validiert die Gültigkeit des Matrix-OpenID-Token mit Hilfe des Matrix-Homeserver [8-9]
      4.  
          
    4. ermittelt den handelnden Akteuer anhand des Status von isInsurance in der Föderationsliste für den Matrix-Homeserver[10]
      5.  
          
         
           
      1. bei isInsurance=false(Mitarbeiter im Gesundheitswesen) wird ein search-access_token mit aud:https://fhir-directory.vzd.ti-dienste.de/search erzeugt [11]
        2.  
           
      2. bei isInsurance=true(Versicherter) wird ein search-access_token mit aud:https://fhir-directory.vzd.ti-dienste.de/fdv/search erzeugt [12]
         
        3.  
          
       
          
    5. übermittelt das search-access_token an den Client [13]
      6.  
         
     
        
 
        
 
      
 
      
 
       Vorbedingung 
       Der Nutzer ist an seinem Homeserver registriert. 
      
 
      
 
       Nachbedingung 
       Der TI-Messenger-Client hat alle gefundenen Einträge empfangen. 
      
 
      
    
 
 
 
  
 
Abbildung 3: Sequence diagram /search
 [<=]

  

  

  
Akzeptanzkriterien für den Anwendungsfall AF_10036 Nutzer sucht OrganizationDirectory- und PractitionerDirectory-Einträge im VZD-FHIR-Directory

  

   
ML-123485 - Authentifizierung am Endpunkt /search (VZD-FHIR-Directory, Sicherheitsgutachten)

   
Am Endpunkt /search des FHIR-Proxy darf die Authentifizierung nur für Requests erfolgreich sein, die ein gültiges search-access_token im Authentication Header enthalten, das vom Auth-Service ausgestellt wurde. Das search-access_token MUSS im aud Feld den Servernamen des VZD-FHIR-Directory und den Endpunkt /search enthalten. [<=]

  

  

   
ML-148295 - Authentifizierung am Endpunkt /fdv/search (VZD-FHIR-Directory, Sicherheitsgutachten)

   
Am Endpunkt /fdv/search des FHIR-Proxy darf die Authentifizierung nur für Requests erfolgreich sein, die ein gültiges search-access_token im Authentication Header enthalten, das vom Auth-Service ausgestellt wurde. Das search-access_token MUSS im aud Feld den Servernamen des VZD-FHIR-Directory und den Endpunkt /fdv/search enthalten. 
 [<=]

  

  
5.2 Eigentümer ändert seinen Eintrag und sucht im FHIR-Directory

  

   
AF_10037-03 - Einträge im VZD-FHIR-Directory ändern und suchen

   

 
 
    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Über die Authentisierung mit HBA/SM(C)-B erfolgt die Authentisierung für die VZD-FHIR-Directory Schnittstellen /owner und /search
 
 Änderung von eigenen Daten im VZD-FHIR-Directory
 Organisationen können ihren Eintrag im VZD-FHIR-Directory an die eigenen Strukturen anpassen. Leistungserbringer können z. B. die TI-Messenger-Adresse in ihrem Eintrag hinzufügen. Der Basiseintrag einer Organisation oder eines Leistungserbringers wird wie bisher durch die Kartenherausgeber erstellt. Die Organisation KANN eigene mit dem Basiseintrag verlinkte FHIR-Ressourcen erstellen, um die Struktur der Organisation abzubilden. Zum Beispiel können Krankenhäuser ihre Fachabteilungen als HealthcareService-Einträge abbilden, die mit dem Organization-Eintrag verlinkt sind.
 Wenn der Org-Admin oder LE kein gültiges owner-access_token vom VZD-FHIR-Directory im Client vorliegt, muss die Authentisierung mittels OIDC an einem IDP der TI-IDP-Föderation erfolgen. Nach erfolgreicher Authentisierung ist die durch den IDP bestätigte Telematik-ID des Leistungserbringers oder der Organisation am Auth-Service bekannt. Für den Aufruf der FHIR-Operationen durch den Client stellt der Auth-Service dem Client ein owner-access_token aus, dass auch die Telematik-ID des LE oder der Organisation enthält.
 
 Suche von Daten im VZD-FHIR-Directory
 Das erzeugte Token kann auch für die Suche im VZD-FHIR-Directory über die /search Schnittstelle genutzt werden. 
  
        
     
         
  • Für die Suche im Zusammenhang von Datenänderungen im VZD-FHIR-Directory kann die Suche in der /owner Schnittstelle genutzt werden.
    •  
        
 
        
     
         
  •  Für die normale Suche MUSS der Client die VZD-FHIR-Directory Suche über die /search Schnittstelle nutzen (die /search Schnittstelle kann entsprechend der Last skaliert werden). 
    •  
        
 		 
      
 
      
 
       Vorbedingung 
       Die Organisation oder der Leistungserbringer hat bereits einen Basiseintrag im VZD-FHIR-Directory.
 Eine Authenticator-App des IDP steht zur Verfügung, mit der die Organisations-Identität oder die Leistungserbringer-Identität bei einem IDP der TI-IDP-Föderation bestätigt werden kann.		 
      
 
      
    
 
 
  
 
Abbildung 4: Sequenzdiagramm VZD-FHIR-Directory Änderung von eigenen OrganizationDirectory- oder PractitionerDirectory-Einträgen 
 [<=]

  

  
Ein Org-Admin-Account kann am Registrierungsdienst nur angelegt werden, wenn eine erfolgreiche Authentisierung
 einer Organisation durchgeführt wurde. Dafür muss das FHIR-Directory den Registrierungsdiensten aller TI-Messenger-Anbieter vertrauen und die erforderlichen Daten (telematikID, Zertifikatstyp, technische Rolle) im id_token des Registrierungsdienstes prüfen.

 Das Vertrauen zu den Registrierungsdiensten der TI-Messenger Anbieter wird bei der Registrierung des TI-Messenger-Anbieters
 beim FHIR-Directory für die Schnittstelle I_VZD_TIM_Provider_Services hergestellt (siehe auch Kap. 4.2.1.4 Schnittstelle FHIRDirectoryTIMProviderAPI).

  
  
  
Die Abfrage der owner-access_token erfolgt entsprechend dem Kontext / Client / relevanten IDP über die dazu passende URL.
 Aktuell wird nur der IDP-Dienst unterstützt und damit ist die entsprechende URL /signin-gematik-idp-dienst
 Nach erfolgreicher Prüfung stellt das FHIR-Directory ein owner-access_token aus und gibt es zurück.
 Wird der Auth-Service des VZD-FHIR-Directory ohne Token aufgerufen, muss er die Authentifizierung entsprechend OpenID Connect durchführen.
 Der Auth-Service soll die Authentifizierung entsprechend OpenID Connect auch für Zugriffe durch Org-Admins
 (SMC-B/Organization) - zusätzlich zur Authentifizierung mit RegService-OpenID-Token - unterstützen.

  
TI-Messenger Authentifizierung mit dem gematik Authenticator - Anbieten eines Polling Endpunktes
 Wenn der Authenticator der gematik von Clients genutzt wird, um eine Authentifizierung auf Basis von Smartcards zu realisieren, dann ist es notwendig am Ende des Prozesses, die Kontrolle wieder an den Client zu übergeben und diesen mit den notwendigen Informationen für die weiteren Prozessschritte zu versorgen. Im folgenden werden die Anpassungen am Auth-Service des VZD-FHIR Directories beschrieben, die notwendig sind, um eine Anmeldung unter Verwendung des gematik Authenticators zu realisieren.
 Beim Anmeldevorgang verwendet der User eine Smartcard als Authentifizierungsmittel. Der Ablauf orientiert sich hierbei an den OIDC-Vorgaben zur Client initiated backchannel authentication. Um die Kollisionen mit standard OAuth2 Grants zu vermeiden, definiert die gematik einen eigenen Grant urn:telematik:params:grant-type:decoupled als Extension.
 Für die Authentifizierung über den gematik-Authenticator übernimmt der Client den Aufruf des Authenticators und das VZD-FHIR-Directory stellt einen Endpunkt bereit, über den der Status des Authentifizierungsvorgangs abgefragt werden kann.

  

  

  
Abbildung 5 : Sequence diagram - Authentifizierung mit dem gematik Authenticator

  

  
Der FHIR VZD muss für diese Authentifizierung folgende Funktionalitäten bereitstellen

  

   
    

     Funktionalität
     Anforderung
    

    

     Bereitstellung des initalen authenticate Endpunkt am Auth-Service
     Das VZD-FHIR Directory muss einen /owner-authenticate-decoupled Endpunkt anbieten der POST Request mit dem übergebene grant_type urn:telematik:params:grant-type:decoupled akzeptiert.
 
      
    
       
  • neuer owner Endpunkt
    • 
      

      

       
POST /owner-authenticate-decoupled HTTP/1.1
Host: https://fhir-directory-ref.vzd.ti-dienste.de/
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Atelematik%3Aparams%3Agrant-type%3Adecoupled

       

      
 Erhält das VZD-FHIR Directory eine derartige Anfrage wird ein Autorisierungsauftrag mit den Werten: 
      

       
    
        
  • auth_reg_id
    • 
        
  • state
    • 
        
  • owner-accesstoken (in diesem Moment noch unbefüllt)
    • 
        
  • code_challenge
    • 
       

      
erstellt und es werden folgende Daten an den Client im Response zurück geliefert:
 
      
    
       
  • owner Response
    • 
      

      

       
    
        
  • expires_in: definiert die Zeit, die die auth_reg_id gültig ist und genutzt werden kann in Sekunden
    • 
        
  • interval: definiert das Mindestwarteintervall zwischen 2 Pollinganfragen
    • 
       

      

    

    

     Bereitstellung eines neuen polling Endpunktes am Auth-Service
     Das VZD-FHIR Directory muss einen Endpunkt anbieten, der von Clients genutzt werden kann, um den Status eines Autorisierungsauftrages abzufragen. Dazu übergibt ein anfragender Client die folgenden Werte (wobei ist durch VZD festgelegter Endpoint, welcher im Schritt 06 dem Client über poll_uri mitgeteilt wird) 
      
    
       
  • Token Request
    • 
      

      

       POST /oauth/v2/oauth-token HTTP/1.1
       
 Host: idsvr.example.com
       
 Content-Type: application/x-www-form-urlencoded
       

       
 grant_type=urn%3Atelematik%3Aparams%3Agrant-type%3Adecoupled
       
 auth_req_id=bspuw6ea-scst-u5hn-p3nt-37khzwY4g
       

      

 Es wird geprüft, ob für die auth_req_id noch gültig ist und bereits ein owner-accesstoken vorliegt:

 a) Es liegt ein passendes Token vor: Dann antwortet der Auth-Service in seinem Response mit dem entsprechenden owner-accesstoken:
 
      
    
       
  • Token Response Success
    • 
      

      

       HTTP/1.1 200 OK
       
     Content-Type: application/json
       
     Cache-Control: no-store
       

       
     {
       
      "access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN"
       
      "token_typ": "Bearer"
       
      "expires_in": "86400"
       
 }
       

      

      

       
      

 b) liegt kein passendes Token vor dann antwortet der Server mit: 
      
    
       
  • Token Response Error
    • 
      

      

       
       HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-cache, no-store

 {
   "error": [ERROR_REASON]
 }

      

 Die ERROR_REASON kann die folgenden Werte annehmen:
      

       
    
        
  • authorization_pending - Der Authentifizierungsprozess ist noch nicht abgeschlossen
    • 
        
  • slow_down - Wenn der Token Request noch nicht abgeschlossen ist und der Client hat den Request schneller als 3 Sekunden gestellt.
    • 
        
  • access_denied - Der Authentifizierungsprozess konnte im Hintergrund nicht erfolgreich durchgeführt werden. Das minimal erlaubte Polling-Interval wird auf 3 Sekunden festlgelegt. Das VZD speichert den Zeitstempel der letzten Polling-Anfrage, sodass bei der nächsten Anfrage mit dem gleichen auth_req_id der letzte Zeitstempel abgerufen werden kann (z.B. in der gleichen Datenbanktabelle). Der Zeitunterschied des aktuellen Zeitstempel und den letzten Zeitstempel muss im Minimum 3 Sekunden betragen.
    • 
       

      

    

    

     Bereitstellung einer neuen Redirect_uri
     Aktuell liefert die vom VZD-FHIR Directory verwendete Redirect_uri (/signin-gematik-idp-dienst) bei Übergabe des Auth_code und des state einen owner-accesstoken zurück. Diese Rückgabe ist nicht notwendig, wenn der Authenticator die Redirect_uri direkt aufruft.
    

   
  

  

  
Akzeptanzkriterien für den Anwendungsfall AF_10037 OrganizationDirectory-Einträge im VZD-FHIR-Directory ändern

  

   
ML-123874 - Nur Einträge mit eigener Telematik-ID verändern (VZD-FHIR-Directory)

   
Im bei der Authentifizierung verwendeten Accesstoken ist die Telematik-ID des Nutzers enthalten. Nur der Eintrag (PractitionerDirectory oder OrganizationDirectory) mit der eigenen Telematik-ID darf verändert werden. Dabei dürfen nur die Attribute verändert werden, die nicht vom VZD-LDAP-Directory synchronisiert werden.
 [<=]

  

  

   
ML-148324 - Authentifizierung am Endpunkt /owner (VZD-FHIR-Directory, Sicherheitsgutachten)

   
Am Endpunkt /owner des FHIR-Proxy darf die Authentifizierung nur für Nutzer erfolgreich sein, die ein gültiges Accesstoken vom VZD-FHIR-Directory vorweisen. Das Accesstoken MUSS im aud Feld den Servernamen des VZD-FHIR-Directory und den Endpunkt /owner enthalten. .
 [<=]

  

  

   
ML-136899 - AF_10037 IDP-Dienst ID-TOKEN Prüfung (VZD-FHIR-Directory)

   
Die ID_TOKEN Prüfung basiert auf Informationen aus dem IDP Discovery Dokument des IDP-Dienstes.
 Die URL des Downloadpunktes lautet im Internet: "https://idp.app.ti-dienste.de/.well-known/openid-configuration". 
 Das Discovery Dokument muss vor Ausführung der Prüfungen für die aktuelle Umgebung (RU/TU/PU) eingelesen worden sein.
 
    

 Die vom IDP-Dienst ausgestellten ID_TOKEN müssen vom VZD-FHIR-Directory nach folgenden Kriterien geprüft werden:
 
    
    
     [<=]

  

  

   
ML-165946 - AF_10037 TIM Registrierungsdienst id_token Prüfung (VZD-FHIR-Directory)

   
Die vom Registrierungsdienst ausgestellten id_token müssen vom VZD-FHIR-Directory geprüft werden:
 
 
    

    

     [<=]

  

  

   
ML-136887 - AF_10037 TI-Provider-Access-Token Prüfung (VZD-FHIR-Directory)

   
Die TI-Provider-Access-Token müssen vom VZD-FHIR-Directory für den Endpunkt /tim-provider-services geprüft werden:
 
    

    
     [<=]

  

  

   
ML-156761 - Selbst angelegte FHIR Ressourcen MÜSSEN mit dem eigenen Basiseintrag verlinkt sein (VZD-FHIR-Directory)

   
Alle selbst durch den Besitzer angelegten FHIR-Ressourcen MÜSSEN mit dem eigenen Basiseintrag (Practitioner, Organization)  direkt oder indirekt - über HealthcareService bzw. PractitionerRole - verlinkt sein. Wenn keine korrekte Verlinkung angegeben ist, dann MUSS der FHIR-Proxy das Erzeugen oder die Änderung der FHIR Ressource mit der Fehlermeldung (HTTP 422 Unprocessable Entity) ablehnen.
 [<=]

  

  
5.3 Anwendungsfälle der TI-Messenger-Anbieter im VZD-FHIR-Directory

  

   
AF_10048-02 - Anwendungsfälle der TI-Messenger-Anbieter im VZD-FHIR-Directory

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Für den Betrieb eines TI-Messenger-Fachdienstes ist es erforderlich, alle an der Föderation beteiligten Matrix-Domänen zu kennen, um nicht an der Föderation beteiligte Matrix-Domänen ausschließen zu können.
 Die Domänen werden im VZD-FHIR-Directory in der Föderationsliste gespeichert.  Der TI-Messenger-Anbieter verwaltet seine Einträge im VZD-FHIR-Directory selbst. Dazu beantragt der TI-Messenger-Anbieter für seinen Registrierungsdienst Client Credentials für die Nutzung der Schnittstelle I_VZD_TIM_Provider_Services. Mit den Credentials erhält der Registrierungsdienst vom VZD TI-Provider-OAuth-Server ein ti-provider-accesstoken. Dieses tauscht er bei dem VZD-FHIR-Directory Auth-Service gegen ein provider-accesstoken, das zur Authentifizierung an der Schnittstelle genutzt wird. Nach erfolgreicher Authentisierung kann der Registrierungsdienst die Operationen zur Verwaltung der Föderationsliste nutzen.
 
 Um die Gesamtheit der an der Föderation beteiligten Matrix-Domainnamen zu erhalten, wird die Operation GET /FederationList aufgerufen. Optional KANN die bereits bekannte Version im Request angegeben werden. Als Ergebnis erhält der Registrierungsdienst eine Liste der Hashes der an der Föderation beteiligten Domainnamen oder keine Liste, falls keine neuere Version existiert. Die Hashes der Domainnamen werden verwendet, um zu verhindern, dass jeder TI-Messenger-Anbieter alle Domainnamen im Klartext kennt.
 		 
      
 
      
 
       Vorbedingung 
       Der Registrierungsdienst des TI-Messenger-Anbieters ist bereits als Nutzer des VZD-FHIR-Directories registriert und hat TI-Provider OAuth Client Credentials (client_id und client_secret) für die Umgebungen RU, TU und PU erhalten. 
      
 
      
    
 
 
    
 
     
     
 
    
 
Abbildung 6: VZD-FHIR-Directory_Sequenzdiagramm_TI-Messenger-Provider-Services
 [<=]

  

  

   
ML-123881 - Authentifizierung an der Schnittstelle I_VZD_TIM_Provider_Services (VZD-FHIR-Directory, Sicherheitsgutachten)

   
An der Schnittstelle I_VZD_TIM_Provider_Services darf die Authentifizierung nur für Clients erfolgreich sein, die ein gültiges provider-accesstoken vom OAuth-Server des VZD-Anbieters vorweisen. 
 [<=]

  

  
5.3.1 Eintragen einer Matrix Domain - Matrix-Server Discovery

  
Über die Matrix-Server Discovery muss

  
  
über die Matrix Funktion “Server Discovery” die konkrete Matrix-Chat-Server-URL inkl. verwendeten Port ermitteln und in die Föderationsliste übernehmen.

  
Dies ist notwendig, da der Standardport 443 nicht von allen Matrix-Servern verwendet wird, die Matrix-Chat-Server-URL von der gewünschten Domain abweichen kann und sich Konfigurationen nachträglich ändern können.

  

  
Server-URL-Syntax

  
<Matrix-Homeserver-URL>:443/.well-known/matrix/server 

  
Beispiel-URL

  
https://matrix.dev.service-ti.de/.well-known/matrix/server/

  
Beispiel Ergebnis

  
{

  
  "m.server": "delegated.example.com:1234"

  
}

  
Bei dem Aufruf des WellKnown-Dokuments (Server Discovery) muss es möglich sein, Redirect-URLs zu folgen. Damit diese Redirect-URLs nicht durch die Firewall blockiert werden, können in Schnittstelle I_VZD_TIM_Provider_Services über die "domainAdministration" Operationen (addTiMessengerDomain, updateTiMessengerDomain) mit dem optionalen Attribut “redirectDomains” Redirect-URLs übergeben werden. Diese werden persistiert und in der Firewall freigeschaltet.

  
Die persistierten redirectDomains müssen im Ergebnis der Operation getTiMessengerDomain enthalten sein, dürfen aber nicht in der Föderationsliste enthalten sein (Operation getFederationList).

  
Bei redirectDomains ist zu beachten

  
  
Initiale Ermittlung des Server-Ports inkl. ServerUrl-Anpassung

  
    
   
  1. Bei dem Hinzufügen von Einträgen (Matrix-Servern) in der Federations-Liste wird die Matrix-Chat-Server-URL mit dem Standardport 443 gesetzt.
    2. 
   
  2. Zudem muss der konkrete Port asynchron durch das von Matrix bereitgestellte Discovery-Dokument ermittelt werden.
     (Für die Beschreibung Server Discovery siehe Matrix-Spezifikation Server-Server API ).
    3. 
   
  3. 
    
      
     
    1. Der Server Discovery Lookup erfolgt asynchron. Die Häufigkeit wird durch Konfigurationsparameter gesteuert.
      2. 
     
    2. Es kommt vor, dass das Discovery-Dokument zum Zeitpunkt der Ermittlung aufgrund von einer ausstehender Firewall/Squid-Freigabe nicht erreichbar ist.
       Eine entsprechende Warning muss im TI-Service-Provider-Log protokolliert werden.
       Mit dem nächsten Lauf (je nach konfigurierter Häufigkeit) muss der nächste Versuch erfolgen.
      3. 
     
    3. Das Server-Disovery-Dokument muss zwingend auf dem Port 443 erreichbar sein.
      4. 
    
    4. 
  

  
Aktualisierung des Server-Ports inkl. ServerUrl-Anpassung

  
Regelmäßig muss für alle in der Federations-Liste enthaltenen Einträge der Server-Port ermittelt und aktualisiert werden.

  
Das Vorgehen muss dabei wie folgt umgesetzt werden.

  
    
   
  1. Der Server Discovery Lookup erfolgt asynchron. Die Häufigkeit wird durch Konfigurationsparameter gesteuert.
    2. 
   
  2. Es kommt vor, dass das Discovery-Dokument zum Zeitpunkt der Ermittlung aufgrund von einer ausstehender Firewall/Squid-Freigabe nicht erreichbar ist.
     Eine entsprechende Warning muss im TI-Service-Provider-Log protokolliert werden.
     Mit dem nächsten Lauf (je nach konfigurierter Häufigkeit) muss der nächste Versuch erfolgen.
    3. 
   
  3. Das Server Disovery Dokument muss zwingend auf dem Port 443 erreichbar sein.
    4. 
  

  
5.4 Einträge mit dem VZD-LDAP-Directory abgleichen

  

   
AF_10047-01 - Einträge mit dem VZD-LDAP-Directory abgleichen

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Der FHIR-Proxy aktualisiert regelmäßig in einem konfigurierbaren Intervall die im VZD-LDAP-Directory seit der letzten Aktualisierung geänderten Einträge.
 Da es sich um eine interne Schnittstelle des Verzeichnisdienstes handelt, wird nicht vorgegeben, wie die Schnittstelle zu implementieren ist. Die Übertragung der Daten MUSS TLS-verschlüsselt in einem internen Netzwerk des Verzeichnisdienstes erfolgen. Es werden alle geänderten Einträge seit der letzten Aktualisierung durch den FHIR-Proxy vom VZD-LDAP-Directory abgefragt und gemäß [VZD-FHIR-Directory_Mapping_LDAP_to_FHIR] aktualisiert. Dabei MÜSSEN auch im VZD-LDAP-Directory gelöschte Einträge erkannt und ebenfalls im VZD-FHIR-Directory gelöscht werden. 
 Im VZD-FHIR-Directory wird der Wert von Organization.active bzw. PractitionerDirectory.active bei der Synchronisation aus dem VZD-LDAP-Directory entsprechend LDAP Basiseintrags-Attributs "active" gesetzt.
 		 
      
 
      
    
 
  
Abbildung 7: VZD-FHIR-Directory, Aktualisierung der Basiseinträge
 [<=]

  

  

  

   
ML-134278 - Synchronisierung VZD-LDAP-Directory mit FHIR-Directory (VZD-FHIR-Directory)

   
Der VZD FHIR-Proxy muss gewährleisten, dass nach einem konfigurierbaren Intervall die im VZD-LDAP-Directory seit der letzten Aktualisierung geänderten Einträge in das VZD FHIR-Directory synchronisiert wurden.
 [<=]

  

  
5.5 Versicherter sucht Einträge im FHIR-Directory

  

   
AF_10219-01 - Versicherter sucht Einträge im FHIR-Directory

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Für die Suche von Versicherten im FHIR-Directory nach Organisationen (HealthcareServiceDirectory-Einträgen), Practitioner'n (PractitionerRoleDirectory-Einträgen) und Endpoints (EndpointDirectory-Einträgen) eine Authentisierung der Fachanwendung am Auth-Service patient-authenticate Endpunkt erforderlich. Der Ablauf entsprechend Abbildung "Sequence diagram /fdv/search":
 
        
     
         
  1. Der Client prüft, ob er ein gültiges search-access_token vom FHIR VZD Auth-Service vorliegen hat. [1]
    2.  
         
  2. Client Anfrage von search-access_token [2]
     Wenn im Client kein gültiges search-access_token vom FHIR VZD Auth-Service vorhanden ist, stellt der Client eine Anfrage an den Fachdienst (siehe I_FHIR_VZD_token_FD.yaml). Vor dieser Anfrage muss sich der Client des Versicherten gegenüber dem Fachdienst authentisiert haben.
    3.  
         
  3. Der Fachdienst benötigt zur Authentisierung gegenüber dem OAuth-Server Client Credentials. Diese erhält er in einem Registrierungsprozess vom Betreiber FHIR-Directory und kann sie z.B. in einem Konfigurationsfile auf dem Fachdienst ablegen. [3]
    4.  
         
  4. Authentisierung des Fachdiensts mit Client Credentials [4-6]
     Der Fachdienst authentisiert sich mit seinen Client Credentials und erhält nach erfolgreicher Prüfung ein service-authz-token.
    5.  
         
  5. Abruf search-access_token [7-10]
     Der Fachdienst tauscht das service-authz-token gegen ein search-access_token ein.
    6.  
         
  6. Cachen vom search-access_token [11]
     Optional kann der Fachdienst das search-access_token cachen und für Anfragen mehrerer Clients nutzen, solange die zeitliche Gültigkeit  von dem search-access_token ausreicht.
    7.  
         
  7. Rückgabe von dem search-access_token an den Client [12]
    8.  
         
  8. Suche im FHIR-Directory [13-17]
     Mit dem search-access_token kann der Client im FHIR-Directory suchen und erhält eine Antwort mit dem Suchergebnis. Wenn das search-access_token ungültig ist (z.B. zeitlich abgelaufen), erhält er als Antwort den HTTP Status Code 401.
    9.  
        
 
        

         Bei der Suche über Endpunkt HealthcareServices werden Ressourcen (HealthcareService, referenzierte Organization, referenzierte Location, ggf. referenzierte Endpoints) vom FHIR VZD aus dem Ergebnis entfernt sobald die referenzierte Organization das Flag (Extension) Organization.organizationVisibility = “hide-erezeptApp” gesetzt hat.
        
 
 
        

         Bei allen Suchen über /fdv/search werden vom FHIR VZD aus dem Ergebnis die Endpoints entfernt, deren Attribut (Extension) Endpoint.extension:endpointVisibility = “hide-versicherte” gesetzt hat.
        
 
        

 
        
 
         
 
        
 
        

        
 
      
 
      
 
       Vorbedingung 
       Der Versicherte ist bei seiner Kasse registriert.
 Der Client des Versicherten hat sich gegenüber dem Fachdienst authentisiert.
 Der Fachdienst des Versicherten hat sich bei FHIR VZD Anbieter für Schnittstelle /fdv/search registriert und Client Credentials vorliegen.		 
      
 
      
 
       Nachbedingung 
       Der Client hat alle gefundenen Einträge empfangen. 
      
 
      
    
 
    

 
 
 
 
Abbildung 8: Sequence diagram /fdv/search
 [<=]

  

  
Hinweis für Hersteller und Anbieter von Clients für Versicherte: Die Client Secrets zur Authentifizierung am OAuth-Server dürfen nur auf einem zentralen Fachdienst/Server verwendet und sicher abgelegt werden, nicht im Client des Versicherten.

  

   
ML-146154 - Authentifizierung am Endpunkt /fdv/search (VZD-FHIR-Directory, Sicherheitsgutachten)

   
Am Endpunkt /fdv/search des FHIR-Proxy darf die Authentifizierung nur für Requests erfolgreich sein, die ein gültiges search-access_token im Authentication Header enthalten, das vom Auth-Service service-authenticate Endpunkt oder tim-authenticate Endpunkt für den Endpunkt /fdv/search ausgestellt wurde. [<=]

  

  
5.6 Erstellen einer Verlinkungsanfrage

  

   
AF_10208 - FHIR-Directory - Erstellen einer Verlinkungsanfrage

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Der authentisierte Institutionsverantwortliche oder Leistungserbringer erstellt eine Verbindungsanfrage für seine Organisation bzw. Practitioner.
 In der Anfrage vermerkt er mit welchen HealthcareService bzw.PractitionerRole sein FHIR VZD Datensatz verbunden werden sollen. 
 Für jeden HealthcareService kann eine Verlinkungsanfrage zu jeder PractitionerRole gestellt werden und für  jede PractitionerRole zu jedem HealthcareService.
 Der FHIR-VZD MUSS dabei sicherstellen, dass für jede Verlinkungsanfrage genau eine PractitionerRole und ein HealthcareService angegeben wird.
 Die Bestätigung der Verlinkung erfolgt beidseitig. Die Antragsteller stimmt bereits mit dem Verlinkungsantrag zu.		 
      
 
      
 
       Vorbedingung 
       Die Institution und der Leistungserbringer sind bereits im FHIR VZD eingetragen.
 Der Nutzer ist authentisiert.		 
      
 
      
 
       Nachbedingung 
       Die Verlinkungsanfrage wurde erfasst. Die Verlinkung ist noch nicht im FHIR VZD sichtbar. 
      
 
      
    
 
 
Abbildung 9: Sequence diagram - Erstellen einer Verlinkungsanfrage
 [<=]

  

  
Akzeptanzkriterien für den Anwendungsfall AF_10208 FHIR-Directory - Erstellen einer Verlinkungsanfrage

  

   
ML-143802 - Erstellen einer Verlinkungsanfrage

   
Der FHIR VZD muss für Verlinkungsanfragen sicherstellen:

    
 [<=]

  

  
5.7 Bestätigen einer Verlinkungsanfrage

  

   
AF_10207 - FHIR-Directory - Bestätigen einer Verlinkungsanfrage

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Der authentisierte Institutionsverantwortliche oder Leistungserbringer bestätigt eine Verbindungsanfrage für seine Organisation bzw. Practitioner.
 Die Bestätigung der Verlinkung erfolgt beidseitig. Die Antragsteller stimmt bereits mit dem Verlinkungsantrag zu.
 Über den FHIR-VZD-Client können alle vorhanden Daten der Verlinkungsanfrage eingesehen werden.		 
      
 
      
 
       Vorbedingung 
       Die Institution und der Leistungserbringer sind im FHIR VZD eingetragen.
 Der Nutzer ist authentisiert.		 
      
 
      
 
       Nachbedingung 
       Die Verlinkungsanfrage wurde bestätigt.
 Die Verlinkungsdaten wurden aktualisiert.
 Die Verlinkung ist im FHIR VZD sichtbar.		 
      
 
      
    
 
 

 Abbildung 10: Sequence diagram - Bestätigen einer Verlinkungsanfrage
 [<=]

  

  
Akzeptanzkriterien für den Anwendungsfall AF_10207 FHIR-Directory - Bestätigung einer Verlinkungsanfrage

  

   
ML-143808 - Bestätigung einer Verlinkungsanfrage

   
Der FHIR VZD muss für die Bestätigung von Verlinkungsanfragen sicherstellen:
 
    
 [<=]

  

  

   
ML-143872 - Ablehnung einer Verlinkungsanfrage

   
Der FHIR VZD muss die Ablehnung von Verlinkungsanfragen (über Anwendungsfall AF_10209 "Löschen einer Verlinkungsanfrage") erlauben:
 
    
 [<=]

  

  
5.8 Löschen einer Verlinkungsanfrage

  

   
AF_10209 - FHIR-Directory - Löschen einer Verlinkung

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Der authentisierte Institutionsverantwortliche oder Leistungserbringer löscht eine Verlinkung für seine Organisation bzw. Practitioner.
 Die Löschung der Verlinkung erfolgt einseitig und kann von jeder verlinkten Partei.		 
      
 
      
 
       Vorbedingung 
       Die Institution und der Leistungserbringer sind im FHIR VZD verlinkt.
 Der Nutzer ist authentisiert.		 
      
 
      
 
       Nachbedingung 
       Die Verlinkung wurde gelöscht.
 Die Verlinkungsdaten wurden aktualisiert.
 Die Verlinkung ist im FHIR VZD nicht mehr sichtbar.		 
      
 
      
    
 
 

 Abbildung 11: Sequence diagram - Löschen einer Verlinkung
 [<=]

  

  
Akzeptanzkriterien für den Anwendungsfall AF_10209 FHIR-Directory - Löschen einer Verlinkung

  

   
ML-143811 - Löschen einer Verlinkung

   
Der FHIR VZD muss für die Löschung von Verlinkungen sicherstellen:
 
    
 [<=]

  

  
5.9 Leistungserbringer/Organisation sucht im FHIR-Directory

  

   
AF_10374 - Leistungserbringer/Organisation sucht im FHIR-Directory

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Über die Authentisierung mit HBA/SM(C)-B ist die Authentisierung für die VZD-FHIR-Directory Schnittstelle /search möglich.
 Diese Authentisierung entspricht Anwendungsfall AF_10037.
 
 Suche von Daten im VZD-FHIR-Directory
 Mit erfolgter Authentisierung kann das Token für die Suche im VZD-FHIR-Directory über die /search Schnittstelle genutzt werden. 
 Für die Suche MUSS der Client die VZD-FHIR-Directory Suche über die /search Schnittstelle nutzen (die /search Schnittstelle kann entsprechend der Last skaliert werden). 		 
      
 
      
 
       Vorbedingung 
       Die Organisation oder der Leistungserbringer hat bereits einen Basiseintrag im VZD-FHIR-Directory.
 Eine Authenticator-App des IDP steht zur Verfügung, mit der die Organisations-Identität oder die Leistungserbringer-Identität bei einem IDP der TI-IDP-Föderation bestätigt werden kann.		 
      
 
      
 
       Ablauf 
       Siehe Anwendungsfall AF_10037. Die Suche MUSS über die VZD-FHIR-Directory /search Schnittstelle erfolgen. 
      
 
      
    
 [<=]

  

  
5.10 Holder sucht im FHIR-Directory

  

   
AF_10375 - Holder sucht im FHIR VZD

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Die Kartenherausgeber der TI benötigen Zugriff auf die FHIR VZD Daten.
 Dafür wird ein zweischrittiges Auth-Verfahren vom FHIR VZD angeboten. Im ersten Schritt erfolgt der Token-Austausch via Client-Secret. Anschließend wird dieser Token an der TI-Provider-Authenticate-Schnittstelle gegen den Access-Token ausgetauscht.
 		 
      
 
      
 
       Vorbedingung 
       Der FHIR VZD-Anbieter stellt einen Registrierungsprozess für Kartenherausgeber bereit. Ist ein Kartenherausgeber bereits für die LDAP VZD SchnittstelleI_Directory_Administration registriert, ist keine erneute Registrierung nötig. 
 Während der Registrierung muss die Berechtigung des Antragstellers (Clients) durch den FHIR VZD-Anbieter geprüft und durch die gematik bestätigt werden. Nach erfolgreicher Registrierung MÜSSEN dem Antragsteller alle nötigen Daten - inklusive OAuth Client Credentials, CA-Zertifikat (welches zur Prüfung des Serverzertifikats durch den Client benötigt wird) zur Nutzung der Schnittstelle bereitgestellt werden.		 
      
 
      
 
       Nachbedingung 
       Der Kartenherausgeber/Holder kann sich authentisieren und hat Lesezugriff über die FHIR VZD /search Schnittstelle. 
      
 
      
 
       Ablauf 
       Die Authentisierung für Kartenherausgeber/Holder entspricht der Authentisierung von TI-Messenger-Anbietern im Anwendungsfall AF_10048. 
      
 
      
    
 [<=]

  

  
5.11 Fachdienst sucht Einträge im FHIR-Directory

  

   
AF_10403 - Fachdienst sucht Einträge im FHIR-Directory

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Für die Suche von Fachdiensten am FHIR-Directory nach Organisationen (HealthcareServiceDirectory-Einträgen) ist eine Authentisierung des Fachdienstes am Auth-Service Endpunkt erforderlich. Der Ablauf entsprechend Abbildung "Sequence diagram /search":
 
        
     
         
  1. Der Fachdienst prüft, ob er ein gültiges search-access_token vom FHIR VZD Auth-Service vorliegen hat. [1]
    2.  
         
  2. Der Fachdienst benötigt zur Authentisierung gegenüber dem OAuth-Server Client Credentials. Diese erhält er in einem Registrierungsprozess vom Betreiber FHIR-Directory und kann sie z.B. in einem Konfigurationsfile auf dem Fachdienst ablegen. [2]
    3.  
         
  3. Authentisierung des Fachdiensts mit Client Credentials [3-5]
     Der Fachdienst authentisiert sich mit seinen Client Credentials und erhält nach erfolgreicher Prüfung ein service-authz-token.
    4.  
         
  4. Abruf search-access_token [6-9]
     Der Fachdienst tauscht das service-authz-token gegen ein search-access_token ein.
    5.  
         
  5. Cachen vom search-access_token [10]
     Optional kann der Fachdienst das search-access_token cachen solange die zeitliche Gültigkeit  von dem search-access_token ausreicht.
    6.  
         
  6. Suche im FHIR-Directory [11-13]
     Mit dem search-access_token kann der Fachdienst im FHIR-Directory suchen und erhält eine Antwort mit dem Suchergebnis. Wenn das search-access_token ungültig ist (z.B. zeitlich abgelaufen), erhält er als Antwort den HTTP Status Code 401.
    7.  
        
 		 
      
 
      
 
       Vorbedingung 
       Der Fachdienst hat sich bei FHIR VZD Anbieter für Schnittstelle /fdv/search registriert und Client Credentials vorliegen. 
      
 
      
 
       Nachbedingung 
       Der Fachdienst hat alle gefundenen Einträge empfangen. 
      
 
      
    
 
 
 
 
Abbildung 12 Sequence diagram - Fachdienst Authentisierung und Suche
 
 [<=]

  

  
5.12 Holder Authentifizierung

  

   
AF_10404 - FHIR VZD - Holder Authentifizierung

   

    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Beschreibung 
       Für die Suche am FHIR-Directory durch einen Holder ist eine Authentisierung am Auth-Service Endpunkt erforderlich. Der Ablauf entsprechend Abbildung "Sequence diagram /search":
  
        
     
         
  1. Der Holder/Client prüft, ob er ein gültiges Holder-Access-Token vorliegen hat. [1]
    2.  
         
  2. Der Holder benötigt zur Authentisierung gegenüber dem FHIR VZD Client Credentials. Diese erhält er in einem Registrierungsprozess vom Betreiber FHIR-Directory.
     Authentisierung des Holders mit Client Credentials [2-4]
     Der Holder authentisiert sich mit seinen Client Credentials und erhält nach erfolgreicher Prüfung ein Key Cloak Holder-Access-Token.
    3.  
         
  3. Abruf Holder-Access-Token [5-8]
     Der Holder/Client tauscht das Key Cloak Holder-Access-Token gegen ein Holder-Access-Token ein.
     Optional kann der Holder/Client das Holder-Access-Token cachen solange die zeitliche Gültigkeit ausreicht.
    4.  
        
 		 
      
 
      
 
       Vorbedingung 
       Der Holder hat sich bei FHIR VZD Anbieter registriert und Client Credentials vorliegen. 
      
 
      
 
       Nachbedingung 
       Der Holder hat das Holder-Access-Token vorliegen. 
      
 
      
    
 
 
 
    
 
     Abbildung 13 Sequence diagram - Holder Authentisierung
     
 
    
 [<=]

  

  

  
5.13 Nutzer setzt Sichtbarkeit für Versicherte

  

   
AF_10377-01 - FHIR-VZD Sichtbarkeit für Versicherte setzen

   
Mit diesem Anwendungsfall kann ein berechtigter Nutzer die Sichtbarkeit der Endpoints, die seinem Practitioner- bzw. Organization-Eintrag zugehordnet sind, für Versicherte verwalten. Möchte der Nutzer verhindern, dass Versicherte z. B. eine hinterlegte MXID über die Suche finden können, dann kann er dies am Endpunkt konfigurieren oder im umgekehrten Fall wieder zurücknehmen. 
 
Tabelle 7: TI-Messenger-Nutzer setzt Sichtbarkeit für Versicherte
 
    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Akteur  
       Mitarbeiter im Gesundheitswesen
 		 
      
 
      
 
       Auslöser  
       Der Nutzer möchte einen Endpunkt im VZD-FHIR Directory für Versicherte nicht sichtbar (a) bzw. sichtbar (b) schalten. 
      
 
      
 
       Komponenten  
        
        
     
         
  • Client
    •  
         
  • FHIR-Proxy
    •  
         
  • FHIR-Directory
    •  
        
 		 
      
 
      
 
       Vorbedingungen  
        
        
     
         
  1. Der Nutzer ist bei einem zugelassenen Client angemeldet.
    2.  
         
  2. Der Nutzer hat nach dem in AF_10037 beschriebenen Verfahren ein owneraccess-token erzeugt.
    3.  
         
  3. Die seinem Practitioner- bzw. Organization-Eintrag zugehörigen Endpoints aus dem VZD-FHIR-Directory liegen dem Client vor.
    4.  
        
 		 
      
 
      
 
       Eingangsdaten  
       FHIR-Endpoint mit neuer endpointVisibility 
      
 
      
 
       Ergebnis 
       Der Eintrag ist in der Suche für Versicherte nicht sichtbar (a) bzw. sichtbar (b). 
      
 
      
 
       Ausgangsdaten 
       FHIR-Endpoint mit aktualisierter endpointVisibility 
      
 
      
    
 
 In der Laufzeitsicht sind die Interaktionen zwischen den Komponenten, die durch den Anwendungsfall genutzt werden, dargestellt. Hierbei handelt es sich um eine vereinfachte Laufzeitansicht, in der zum Beispiel die TLS-Terminierung am FHIR-Proxy auf Grund der Übersichtlichkeit nicht berücksichtigt wurde.
 

 Abbildung 14: Laufzeitsicht - Organization - FHIR-VZD Sichtbarkeit für Versicherte setzen
 
 [<=]

  

  
5.14 Lesen von Zertifikaten I_FHIR_VZD_Certificates

  

   
AF_10407 - Lesen von Zertifikaten von Verzeichniseinträgen I_FHIR_VZD_Certificates

   

 
    
 
      
      
 
       Attribute 
       Bemerkung 
      
 
      
 
       Akteure 
       
 FHIR VZD Client
 		 
      
 
      
 
       Beschreibung 
       Für manche Anwendungsfälle von TI Anwendungen werden Zertifikate benötigt. Diese können aus dem FHIR VZD - über Schnittstelle I_FHIR_VZD_Certificates - gelesen werden.
 
 Um die Schnittstelle I_FHIR_VZD_Certificates nutzen zu können, MÜSSEN sich die FHIR VZD Clients mit einem gültigen Token authentisieren, das vom FHIR-Directory Auth-Service ausgestellt wurde. Akzeptiert werden die folgenden Token:
 
        
     
         
  • search-access_token von der FHIRDirectorySearchAPI Schnittstelle (/search)
    •  
         
  • search-access_token von der FHIRDirectoryFdvSearchAPI Schnittstelle (/fdv/search)
    •  
         
  • Accesstoken von der FHIRDirectoryOwnerAPI Schnittstelle (/owner) 
     
    •  
        
 Mit der FHIR VZD Operation GET /Certificates "read_FhirVZD_Certificates" werden die Zertifikate vom FHIR VZD abgefragt.
 Die Operationen von Schnittstelle I_FHIR_VZD_Certificates sind in I_FHIR_VZD_Certificates.yaml definiert.
  
        
 
      
 
      
 
       Vorbedingung 
       Der FHIR VZD Client benötigt ein gültiges Token.
 Der FHIR VZD Client muss den FHIR VZD Eintrag kennen - z.B. die TelematikID vorliegen haben - für den er die Zertifikate lesen will.		 
      
 
      
 
       Nachbedingung 
       Der FHIR VZD Client hat die Zertifikate für den selektierten FHIR VZD Eintrag vorliegen. 
      
 
      
    
 
 
 
 
    
 [<=]

  

  

  

  
6 Verteilungssicht

  
Das VZD-FHIR-Directory unterstützt initial die Anwendung TI-Messenger; wird zukünftig aber auch die anderen Anwendungen wie ePA und KIM in deren Folgeversionen sowie bisher unbekannte Fachanwendungen und neue Nutzergruppen unterstützen. Es ist daher erforderlich, dass das VZD-FHIR-Directory mit der Anzahl der Nutzerzugriffe skalieren und anwendungsspezifische Ressourcen speichern kann.

  
Der FHIR-Proxy MUSS in mehreren Instanzen betrieben werden können, die die Schnittstellen Richtung Internet für Abfragen der TI-Messenger-Nutzer und Änderungen durch die Besitzer implementieren. Das Load-Balancing der Client-Requests erfolgt per DNS, indem für jede Instanz des FHIR-Proxy ein A und ein AAAA Resource Record für die RU, TU und PU FQDNs der Schnittstellen im DNS eingetragen wird. Instanzen des FHIR-Proxies werden je nach Last hinzugefügt oder entfernt.

  
Die FHIR-Proxy sind auch die HTTP-Load-Balancer für die Lesezugriffe auf FHIR-Directory-Instanzen. Für den Schreibzugriff wird eine Instanz implementiert. Die Datenbanken der Instanzen für den Lesezugriff werden mit der Datenbank für den Schreibzugriff synchronisiert.

  
Eine weitere Komponente setzt die Aktualisierung der Basiseinträge im FHIR-Directory mit den geänderten Daten aus dem VZD-LDAP-Directory um. Zusätzlich implementiert diese Komponente die Schnittstelle I_VZD_TIM_Provider_Services.

  

  

  
Abbildung 15: VZD-FHIR-Directory, Verteilungssicht  

  
7 Anhang A – Verzeichnisse

  
7.1 Abkürzungen

  

   
    

     Kürzel

     Erläuterung

    

    

     AF
     Anwendungsfall
    

    

     DNS
     Domain Name System
    

    

     FHIR
     Fast Healthcare Interoperable Resources
    

    

     FQDN
     Fully Qualified Domain Name
    

    

     LDAP
     Lightweight Directory Access Protocol
    

    

     OWASP
     Open Web Application Security Project
    

    

     PU
     Produktivumgebung
    

    

     RU
     Referenzumgebung
    

    

     SHA
     Secure Hash Algorithm
    

    

     TLS
     Transport Layer Security
    

    

     TI
     Telematikinfrastruktur
    

    

     TIM
     TI-Messenger (ausschließliche Verwendung der Abkürzung in Attributen, Parametern oder URLs)
    

    

     TU
     Testumgebung
    

    

     VZD
     Verzeichnisdienst
    

   
  

  
7.2 Glossar

  

   
    

     Begriff

     Erläuterung

    

    

     Funktionsmerkmal
     Der Begriff beschreibt eine Funktion oder auch einzelne, eine logische Einheit bildende Teilfunktionen der TI im Rahmen der funktionalen Zerlegung des Systems.
    

   
  

  
Das Glossar wird als eigenständiges Dokument (vgl. [gemGlossar]) zur Verfügung gestellt.

  
7.3 Abbildungsverzeichnis

  

  

   

   
  

  
7.4 Tabellenverzeichnis

  

  

   

   
  

  
7.5 Referenzierte Dokumente

  
7.5.1 Dokumente der gematik

  
Die nachfolgende Tabelle enthält die Bezeichnung der in dem vorliegenden Dokument referenzierten Dokumente der gematik zur Telematikinfrastruktur. Der mit der vorliegenden Version korrelierende Entwicklungsstand dieser Konzepte und Spezifikationen wird pro Release in einer Dokumentenlandkarte definiert; Version und Stand der referenzierten Dokumente sind daher in der nachfolgenden Tabelle nicht aufgeführt. Deren zu diesem Dokument jeweils gültige Versionsnummern sind in der aktuellen, von der gematik veröffentlichten Dokumentenlandkarte enthalten, in der die vorliegende Version aufgeführt wird.

  

   
    

     [Quelle]

     Herausgeber: Titel

    

    

     [gemGlossar]
     gematik: Einführung der Gesundheitskarte – Glossar
    

    

     [gemSpec_VZD]
     gematik: Spezifikation Verzeichnisdienst
    

    

     [gemSpec_Krypt]
     gematik: Übergreifende Spezifikation Verwendung kryptographischer Algorithmen in der Telematikinfrastruktur
    

    

     [gemKPT_Betr]
     gematik: Betriebskonzept Online-Produktivbetrieb
    

    

     [VZD-FHIR-Directory_Mapping_LDAP_to_FHIR]
     gematik: VZD Mapping LDAP zu FHIR Ressourcen
 https://github.com/gematik/api-vzd/blob/23456d9ef61263185edfbcaabf09086ba7b26a20/docs/LDAP2FHIR_Sync.adoc  		
    

    

     [Simplifier-FHIR-VZD]
     gematik: FHIR VZD Datenmodell
 https://simplifier.net/vzd-fhir-directory 		
    

    

     [gemSpec_IDP_FD]
     gematik: Spezifikation Identity Provider – Nutzungsspezifikation  für Fachdienste
    

    

     [gemSpec_IDP_Sek]
     gematik: SpezifikationSektoraler Identity Provider
    

    

     [gemSpec_IDP_FedMaster]
     gematik: SpezifikationFederation Master
    

   
  

  
7.5.2 Weitere Dokumente

  

   
    

     [Quelle]

     Herausgeber (Erscheinungsdatum): Titel

    

    

     [CAB-Forum]
     Liste vertrauenswürdiger Zertifikatsherausgeber (Root-CAs) für Anwendungen im Internet
 https://cabforum.org/members/		
    

    

     [ROOT-CA]
     ROOT-CA Download Punkt
 PU-Root https://download.tsl.ti-dienste.de/ECC/ROOT-CA/
 TU-Root https://download-test.tsl.ti-dienste.de/ECC/ROOT-CA/  
 RU-Root https://download-ref.tsl.ti-dienste.de/ECC/ROOT-CA/  		
    

    

     [ROOT-CA-JSON]
     ROOT-CA Download Punkt als JSON-Datei
 PU-Root https://download.tsl.ti-dienste.de/ECC/ROOT-CA/roots.json
 TU-Root https://download-test.tsl.ti-dienste.de/ECC/ROOT-CA/roots.json 
 RU-Root https://download-ref.tsl.ti-dienste.de/ECC/ROOT-CA/roots.json  		
    

    

     [Sub-CA]
     Sub-CA Download Punkt
 PU-Sub https://download.tsl.ti-dienste.de/ECC/SUB-CA/
 TU-Sub https://download-test.tsl.ti-dienste.de/ECC/SUB-CA/ 
 RU-Sub https://download-ref.tsl.ti-dienste.de/ECC/SUB-CA/		
    

    

     [GR-IK-2023-11]
     Gemeinsames Rundschreiben Institutionskennzeichen (IK)
 www.arge-ik.de
 Stand 01.11.2023
 https://www.gkv-datenaustausch.de/media/dokumente/leistungserbringer_1/sonstige_leistungserbringer/GR-IK-2023-11.pdf 

    

   
  

  
Mitgeltende Dokumente und Web-Inhalte

  

   
    

     Quelle

     Herausgeber: Bezeichnung / URL

     Version 
 Branch / Tag

    

    

     [VZD-FHIR-PACKAGE-DIRECTORY]

     https://simplifier.net/packages/de.gematik.fhir.directory/0.10.25

     0.11.24

    

   
  

  
7.6 Versionierung Datenmodell

  
Folgende Versionen der Datenmodell Ressourcen (https://simplifier.net/vzd-fhir-directory/ ) sind für die vorliegende Spezifikation relevant: