gemSpec_TI-M_ePA_V1.1.0_CC







Elektronische Gesundheitskarte und Telematikinfrastruktur





Spezifikation

TI-Messenger ePA




    
Version 1.1.0_CC
Revision 1003361
Stand 30.09.2024
Status zur Abstimmung freigegeben
Klassifizierung öffentlich_Entwurf
Referenzierung gemSpec_TI-M_ePA

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 13.06.2024 initiale Erstellung gematik
1.1.0_CC 30.09.2024 zur Abstimmung freigegeben gematik

Inhaltsverzeichnis

1 Einordnung des Dokumentes

1.1 Zielsetzung

Die vorliegende Spezifikation definiert die Anforderungen zu Herstellung, Test und Zulassung der Produkttypen TI-M_Client_ePA und TI-M_FD_ePA. Dieses Dokument erweitert die Basisspezifikation [gemSpec_TI-M_Basis] um die für die genannten Produkttypen notwendigen Anpassungen. Für die Produkte gelten weiterhin die in der Basisspezifikation beschriebenen Funktionalitäten, sofern Sie nicht in diesem Dokument erweitert oder eingeschränkt werden.

1.2 Zielgruppe

Das Dokument richtet sich an Hersteller von Frontends für Versicherte (FdV) mit integriertem TI-M Client ePA, an Hersteller von TI-M FD ePA und an Anbieter, welche die beschriebenen Produkttypen betreiben.

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. Dokumentenlandkarte, Produkttypsteckbrief, Leistungsbeschreibung) 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 die von dem Produkttyp bereitgestellten (angebotenen) Schnittstellen. Benutzte Schnittstellen werden hingegen in der Spezifikation desjenigen Produkttypen beschrieben, der diese Schnittstelle bereitstellt. Auf die entsprechenden Dokumente wird referenziert (siehe auch Anhang ).

Die vollständige Anforderungslage für den Produkttyp ergibt sich aus weiteren Konzept- und Spezifikationsdokumenten. Diese sind in den Produkttypsteckbriefen der Produkttypen TI-M_Client_ePA und TI-M_FD_ePA verzeichnet.

1.5 Methodik

Anwendungsfälle und Anforderungen als Ausdruck normativer Festlegungen werden durch eine eindeutige ID, Anforderungen zusätzlich durch die dem RFC 2119 [RFC2119] entsprechenden, in Großbuchstaben geschriebenen deutschen Schlüsselworte MUSS, DARF NICHT, SOLL, SOLL NICHT, KANN gekennzeichnet.

Da in dem Beispielsatz „Eine leere Liste DARF NICHT ein Element besitzen.“ die Phrase „DARF NICHT“ semantisch irreführend wäre (wenn nicht ein, dann vielleicht zwei?), wird in diesem Dokument stattdessen „Eine leere Liste DARF KEIN Element besitzen.“ verwendet. Die Schlüsselworte werden außerdem um Pronomen in Großbuchstaben ergänzt, wenn dies den Sprachfluss verbessert oder die Semantik verdeutlicht.

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

bzw.

<AFO-ID> - <Titel der Afo>
Text / Beschreibung
[<=]

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

2 Systemüberblick

Für die Einbindung der Versicherten werden basierend auf der Basisspezifikation [gemSpec_TI-M_Basis] Anpassungen vorgenommen, die auf Clientseite im Produkt TI-M Client ePA und auf Serverseite im Produkt TI-M FD ePA aufgehen.

2.1 Akteure und Rollen

Mit dieser Spezifikation werden die Versicherten als Akteure in die TI-Messenger Föderation eingebunden. Versicherte können zukünftig über einen TI-Messenger Client im Frontend des Versicherten der ePA (TI-M Client ePA) sicher und schnell Inhalte austauschen.

Der Messenger-Service wird für den Versicherten immer von der jeweiligen Krankenkasse bereitgestellt.

2.1.1 Rolle: "Versicherter"

Der TI-M ePA führt die Rolle "Versicherter" ein. Versicherten stehen die gleichen Funktionalitäten zur Verfügung wie einem Akteur in der Rolle "User" der Spezifikation [gemSpec_TI-M_Basis]. Diese Funktionalitäten können durch die Inhalte dieser Spezifikation erweitert oder eingeschränkt werden.

2.2 Nachbarsysteme

Die folgende Grafik zeigt die Schnittstellen zu Nachbarsysteme für den TI-M Client ePA und den TI-M FD ePA.

Abbildung 1: Kontextabgrenzung

Der TI-M Client ePA hat Schnittstellen

  • zu anderen TI-M Clients zum Austausch von Kontaktinformationen (z.B. via QR-Code Scan),
  • zum sektoralen IDP. Es werden die gleichen Verfahren wie beim ePA FdV (mit Single Sign On, wenn vorhanden (siehe [gemSpec_IDP_Frontend]) verwendet,
  • zum VZD-FHIR-Directory zur Suche nach Kontakten in Organisationen oder im Verzeichnis der Practitioner,
  • zum externen Push Provider um Benachrichtigungen zu erhalten und
  • zum TI-M FD ePA für Versicherte.

Der TI-M FD ePA hat Schnittstellen

  • zum TI-M Client ePA für Versicherte,
  • zum Org-Admin Client des Kostenträgers (KTR) zur Verwaltung der Akteure,
  • zum sektoralen IDP. Es werden die gleichen Verfahren wie beim ePA FdV mit Single-Sign-On verwendet, wenn vorhanden (siehe [gemSpec_IDP_Sek]),
  • zum FHIR-Verzeichnisdienst zur Pflege und zum Bezug der Föderationsliste,
  • zur Komponenten PKI für die Erzeugung und Prüfung von Zertifikaten aus dem Vertrauensraum der TI,
  • zu anderen TI-M FD, um innerhalb der TI-Messenger Föderation die Kommunikation mit Nutzern anderer TI-M FD zu ermöglichen und
  • zum Push Gateway, um Benachrichtigungen für Nutzer zu versenden.

2.2.1 Authentifizierungs-Dienst für Akteure in der Rolle "Versicherter"

Für die Verwaltung der Identitäten der Akteure in der Rolle "Versicherter" stellen die Krankenkassen einen sektoralen IDP bereit. Die Spezifikation für den sektoralen IDP ist unter [gemSpec_IDP_Sek] zu finden. Für den TI-M ePA bindend sind Anforderungen aus dem Dokument [gemSpec_IDP_Frontend] für den Client und Anforderungen aus [gemSpec_IDP_FD] für den Fachdienst, die den jeweiligen Produkttypsteckbriefen zu entnehmen sind und deren Inhalte zusätzlich in den Kapiteln zum Client (3.1.2 Auth Modul) und zum Fachdienst (3.2.2.1 Schnittstelle für Authentifizierungsverfahren) aufgeführt werden.

A_25488 - IDP-Sek_KTR

Als Authentifizierungs-Dienst für die Akteure in der Rolle "Versicherter" MUSS der sektorale IDP mit Anbieterzulassung nach [gemAnbT_IDP-Sek_KTR_ATV] verwendet werden, der die Akteure für die Fachdienste ePA, eRezept und TI-M beheimatet. [<=]

2.2.2 VZD-FHIR-Directory

Beim VZD-FHIR-Directory gibt es gegenüber der Basisspezifikation nur minimale Anpassungen.

  • Nach der Authentisierung wird für die Akteure ein individueller searchaccess-token bereitgestellt.
  • Für die Suche der Akteure in der Rolle "Versicherter" wurde ein eigener Endpunkt bereitgestellt (3.1.1 VZD-FHIR-Directory).

3 Zerlegung des Produkttyps (Systemkomponenten)

In den folgenden Kapiteln werden die Komponenten des Clients und der Services in einer Bausteinansicht visualisiert.

3.1 TI-M Client ePA

Die folgende Grafik zeigt die Komponenten eines TI-M Clients ePA. Farblich hervorgehoben sind diejenigen Komponenten gegenüber der Basisspezifikation [gemSpec_TI-M_Basis], die im Rahmen der in dieser Spezifikation vorgestellten Features angepasst werden müssen (blau) und Komponenten, die neu hinzugekommen sind (grün).

Abbildung 2: TI-M Client ePA Komponentendiagramm

Neu hinzugekommen ist für die Nutzerauthentifizierung der sektorale IDP auf den in Kapitel 2.2.1 Authentifizierungs-Dienst für Akteure in der Rolle "Versicherter" eingegangen wird. Am VZD-FHIR-Directory ändert sich lediglich der Endpunkt für die Suche, da für Akteure in der Rolle "Versicherter" ein neuer Endpunkt bereitgestellt wird.

A_26382 - Auftrennung separater Benutzeroberflächen in Module

Die TI-M Clients ePA MÜSSEN separate Benutzeroberflächen für Kommunikation und Administration und die damit verbundenen Funktionalitäten in eigenständige Module auftrennen, die unabhängig voneinander ausgeliefert und betrieben werden können. [<=]

A_26383 - Keine Administrationsfunktion für Akteure in der Rolle "Versicherter"

Anbieter von TI-M Clients ePA MÜSSEN sicherstellen, dass kein TI-M Client ePA mit Administrationfunktionalität und -benutzeroberfläche (Org-Admin-Client) an Akteure in der Rolle "Versicherter" ausgeliefert wird. [<=]

3.1.1 VZD-FHIR-Directory

A_25681-01 - VZD-FHIR-Directory Suche

Der TI-M Client ePA MUSS für die Suche im VZD-FHIR-Directory die Schnittstelle /fdv/search verwenden. [<=]

3.1.2 Auth Modul

Für die Interaktion mit dem sektoralen IDP wird auf Clientseite ein Authenticator-Modul bereitgestellt, dessen Anforderungen in [gemSpec_IDP_Sek] definiert sind. Für den TI-M Client ePA sind die Anforderungen an Clients aus der Spezifikation Identity Provider - Frontend ([gemSpec_IDP_Frontend] zu beachten und werden im Produktypsteckbrief aufgeführt.

3.1.3 Weitere Ergänzungen/Einschränkungen zur Matrix-Spezifikation

A_26015 - Anlage öffentlicher Räume nicht anbieten

Der TI-M Client ePA DARF dem Akteur in der Rolle Versicherter NICHT die Anlage öffentlicher Räume anbieten. [<=]

3.2 TI-M FD ePA

Die folgende Grafik visualisiert die Komponenten eines TI-M FD ePA auf Serverseite , die im Rahmen der in diesem Dokument beschriebenen Features hinzukommen oder angepasst werden müssen. Farblich hervorgehoben sind diejenigen Komponenten gegenüber der Basisspezifikation [gemSpec_TI-M_Basis], die im Rahmen der in dieser Spezifikation vorgestellten Features angepasst werden müssen (blau) und Komponenten, die neu hinzugekommen sind (grün).

Abbildung 3: TI-Messenger-Service Komponentendiagramm

3.2.1 Registrierungs-Dienst

Der Registrierungs-Dienst wird angepasst, da nur Kostenträger in die Lage versetzt werden sollen, Messenger-Services für Akteure in der Rolle "Versicherter" zu bestellen (siehe 5.1 Einschränkung zu Anwendungsfall AF_10060 - Bereitstellung eines Messenger-Service für eine Organisation).

3.2.2 Messenger-Service

3.2.2.1 Schnittstelle für Authentifizierungsverfahren

Der Messenger-Service muss für die Authentifizierung der Akteure in der Rolle "Versicherter" an den sektoralen IDP angeschlossen werden.  Anschließend können Inhalte des vom sektoralen IDP ausgestellten ID_TOKEN bei der Account Anlage verwendet werden (siehe A_25706 - AF_10234 - Erzeugung der MXID (Bei Registrierung) & A_25707 - AF_10234 - Erzeugung des Display Name). Für den TI-M FD ePA sind damit die Fachdienstanforderungen aus der Spezifikation Identity Provider – Nutzungsspezifikation für Fachdienste ([gemSpec_IDP_FD] entsprechend bindend und im Produktypsteckbrief aufgeführt.

A_25696 - OIDC mit pushed authorization requests

Der TI-Messenger Service für ePA MUSS für die Registrierung eines neuen Accounts und für das Login eines Akteurs in der Rolle Versicherter den OIDC authorization code flow mit pushed authorization requests am sektoralen IDP unterstützen. [<=]

Hinweis: Die vom sektoralen IDP grundsätzlich unterstützten Authentifizierungsverfahren sind in [gemSpec_IDP_Sek#Authentifizierungsverfahren] beschrieben.

3.2.2.2 Messenger-Proxy

Das Berechtigungsmanagement des Messenger-Proxy wird erweitert, um die direkte Versicherten-zu-Versicherte Kommunikation zu unterbinden (siehe 5.3 Berechtigungsmanagement - Anpassungen). Zusätzlich kann der Proxy noch angepasst werden, um Pushed Authorization Requests gegenüber dem Sektoralen IDP zu realisieren (siehe 5.2 Feature Identifikation und Login eines Benutzers ).

3.2.2.3 Ergänzungen zur Matrix-Spezifikation

A_25996 - Keine öffentlichen Räume

Der Matrix-Homeserver MUSS die Anlage öffentlicher Räume durch einen Akteur in der Rolle Versicherter unterbinden. Die API zur Anlage eines Raumes DARF den Preset "public_chat" NICHT zulassen und MUSS eine join_rule mit dem Wert "public" unterbinden. [<=]

A_26290 - Verbot von Profilabfragen ohne gemeinsame Räume

Der TI-M Fachdienst ePA MUSS Requests zu den folgenden Endpunkten mit einer HTTP 403 Response ablehnen, sofern der anfragende Nutzer keine gemeinsamen Räume mit dem angefragten Nutzer hat:

  • GET /_matrix/client/v3/profile/{userId}
  • GET /_matrix/client/v3/profile/{userId}/avatar_url
  • GET /_matrix/client/v3/profile/{userId}/displayname
[<=]

A_26375 - Verbot von Suchabfragen ohne gemeinsame Räume

Der TI-M Fachdienst ePA DARF am Endpunkt /_matrix/client/v3/user_directory/search KEINE Profile von Nutzern ausliefern, die keine gemeinsamen Räume mit dem anfragenden Nutzer haben. [<=]

A_26348 - Periodische Entfernung von Nutzern aus verwaisten Räumen

Der TI-M Fachdienst ePA MUSS in regelmäßigen Abständen lokale Nutzer aus Räumen entfernen, in denen sich nur Versicherte befinden. Die Entscheidung, ob ein Nutzer Versicherter ist oder nicht, MUSS dabei durch Abgleich des Domainteils der MXID gegen die aktuell am Messenger-Proxy verfügbare Föderationsliste erfolgen. [<=]

A_26349 - Konfigurierbares Intervall für die periodische Entfernung von Nutzern aus verwaisten Räumen

Der TI-M Fachdienst MUSS das Intervall für die periodische Entfernung von lokalen Nutzern aus Räumen, in denen sich nur Versicherte befinden, per Konfiguration ermöglichen. [<=]

4 Übergreifende Festlegungen

4.1 Betrieb

Im Betrieb verantwortet ein Anbieter des TI-Messengers das Produkt:

  • TI-M Fachdienst ePA

Abbildung 4 Betriebsmodell TI-M ePA

Hinweis zur Abbildung:
Die Abbildung bildet die organisatorischen Kommunikationsbeziehungen aus Sicht des TI-ITSM-Systems zwischen den jeweiligen Entitäten/Anbieterrollen ab. Die Produktverantwortung für das Produkt TI-M Client ePA, welches im ePA FdV integriert ist, liegt beim Hersteller des Versicherten Frontends (siehe auch [gemKPT_Betr]).

A_25823-01 - TI-Messenger Fachdienst Bestandsdaten (ePA)

Der TI-Messenger-Fachdienst ePA MUSS die nachfolgenden Informationen täglich in folgendem JSON Format als HTTP Body an die Betriebsdatenerfassung (BDE) gemäß [gemSpec_SST_LD_BD] liefern:

{
  "abfragezeitpunkt": <Zeitstempel der Abfrage als String im Format ISO 8601: YYYY-MM-DDThh:mm:ssZ>,
  "ci": <CI-ID des abgefragten Fachdienstes gemäß [A_17764] als String>,
  "anzMs": <Anzahl der zum Abfragezeitpunkt instanziierten Messenger-Service als Integer>,
  "anzNu": <Anzahl der zum Abfragezeitpunkt registrierten Nutzer über alle Messenger-Services als Integer>,
  "anzAktNu": <Anzahl der zum Abfragezeitpunkt innerhalb der letzten 30 Tage aktiven Nutzer über alle Messenger-Services als Integer>,
  "anzRa": <Anzahl der zum Abfragezeitpunkt offenen Räume als Integer>,
  "anzEv": <Anzahl Message-Events als Integer, kumuliert>,
  "uaList": [{
    "uaKen": $ua-ken,
    "uaPtv": $ua-Produkttypversion,
    "uaPv": $ua-Produktversion,
    "uaAus": $ua-Auspraegung,
    "uaPlat": $ua-Plattform,
    "uaOsv": $ua-OSv,
    "uaCid": $ua-client_id,
  }],
  "afList": [{
    "md": "$md",
    "TIM.UC_10103-02a_01": $anzahl,
    "TIM.UC_10103-02a_02": $anzahl,
    "TIM.UC_10103-02b_01": $anzahl,
    "TIM.UC_10103-02b_02": $anzahl,
    "TIM.UC_10103-02_03": $anzahl,
    "TIM.UC_10060-02_01": $anzahl,
    "TIM.UC_10060-02_02": $anzahl,
    "TIM.UC_10063-01_01": $anzahl,
    "TIM.UC_10061-03_01": $anzahl,
    "TIM.UC_10061-03_02": $anzahl,
    "TIM.UC_10062-02_01": $anzahl,
    "TIM.UC_10062-02_02": $anzahl,
    "TIM.UC_10036-01_01": $anzahl,
    "TIM.UC_10036-01_02": $anzahl,
    "TIM.UC_10234_01": $anzahl,
    "TIM.UC_10234_02": $anzahl,
    "TIM.UC_10234_03": $anzahl,
    "TIM.UC_10234_04": $anzahl
  }]
}

  • uaList: Das Array MUSS mit Werten entsprechend ihrer Beschreibung befüllt werden. Es DÜRFEN NUR neue Kombinationen der Attribute übermittelt werden, welche zuvor noch nicht übermittelt wurden.
  • uaKen: Datentyp String, SHA1 (Base64-kodiert). Für $ua-ken MUSS die mit SHA1 kodierte Kennung einer bestimmten Client-Ausprägung eingetragen werden. Die Kennung MUSS eindeutig für jede einzigartige Kombination der User-Agent Attribute vergeben werden.*
  • uaPtv: Datentyp String. Für $ua-Produkttypversion MUSS die Produkttypversion des TI-Messenger Clients eingetragen werden.
  • uaPv: Datentyp String. Für $ua-Produktversion MUSS die Produktversion des TI-Messenger Clients eingetragen werden.
  • uaAus: Datentyp String. Für $ua-Auspraegung MUSS die Ausprägung des Clients entsprechend der Spezifikation eingetragen werden. Es DÜRFEN AUSSCHLIEßLICH die Werte "Org-Admin-Client" oder "Messenger-Client" verwendet werden.
  • uaPlat: Datentyp String. Für $ua-Plattform MUSS die Plattform des Clients eingetragen werden. Es DÜRFEN AUSSCHLIEßLICH die Werte "mobil", "stationaer" oder "web" verwendet werden.
  • uaOsv: Datentyp String. Für $ua-OSv MUSS das entsprechende Betriebssystem mit der Version eingetragen werden. Zum Beispiel "Windows 10 Enterprise", "iOS 16.6", "macOS Ventura 13.5.1", "Android 13", "Ubuntu 22.04 LTS" etc.
  • uaCid: Datentyp String. Für $ua-client_id MUSS die client_id eingetragen werden wie sie auch dem TI-Messenger Fachdienst gemäß A_25483 übermittelt wird.
  • afList: Das Array enthält alle Teilschritte aller Anwendungsfälle die am Fachdienst erfasst werden MÜSSEN. Die Keys MÜSSEN alle exakt wie dargestellt übermittelt werden. Die erfasste Anzahl an Aufrufen je Teilschritt (inkl. Fehler) MUSS für $anzahl als Wert (Integer) übermittelt werden. Wenn ein Teilschritt in einem Zeitintervall nicht registriert wurde, MUSS der Wert 0 eingetragen werden.
  • md: Datentyp String. Für $md MUSS die eigene Matrix-Domain des Messenger-Services eingetragen werden, wie sie auch in der Föderationsliste hinterlegt ist.
* Hinweis: Die Kennung dient in erster Linie dem Anbieter zur Differenzierung der Clients im anbieterübergreifenden Betrieb falls der TI-M Client (als zugelassenes Produkt) selbst keine unterschiedliche Kennung (client_id) aufweist.
[<=]

A_26402 - Performance - Rohdaten - Spezifika Fachdienst TI-M ePA - Duration (Rohdatenerfassung v.02)

Der Produkttyp Fachdienst TI-Messenger ePA MUSS bei Rohdaten-Performance-Berichten die Inhalte des Feldes "duration_in_ms" nach den Vorgaben der Tabelle [Berichtsformat_TI-Messenger-Fachdienst ePA] entsprechend der Spalten "Start der Messung" und "Ende der Messung" für die jeweilige TIM-Operation befüllen. [<=]

A_24044-01 - Performance - Rohdaten - Spezifika Fachdienst TI-M ePA - Operation (Rohdatenerfassung v.02)

Der Produkttyp Fachdienst TI-Messenger MUSS bei Rohdaten-Performance-Berichten bzgl. des Feldes "operation" gemäß A_21981-02, die Angabe entsprechend der Spalte "$TIM-Operation" aus [Berichtsformat_TI-Messenger-Fachdienst ePA] befüllen. [<=]

Tabelle 1: Berichtsformat_TI-Messenger-Fachdienst ePA

$TIM-Operation
(Referenz Use Case / Anwendungsfall)
Beschreibung Start der Messung
Ende der Messung
TIM.UC_10103-02a_01 5.1.1 AF - Authentisieren einer Organisation (OIDC):
Redirect to IdP
2 POST I_Registration 4 Redirect to IDP Authorization Endpoint
TIM.UC_10103-02a_02 5.1.1 AF - Authentisieren einer Organisation (OIDC):
Authentisierung über IDP
13 Post I_Registration (auth code) 30 Status
TIM.UC_10103-02b_01 5.1.1 AF - Authentisieren einer Organisation (KIM):
KIM Adresse angeben
18 POST I_Registration
(Eingabe KIM-Adresse)
22 KIM Nachricht mit URL
TIM.UC_10103-02b_02 5.1.1 AF - Authentisieren einer Organisation (KIM):
KIM Authentisierung
23 URL in KIM-Nachricht öffnen 30 Status
TIM.UC_10103-02_03 5.1.1 AF - Authentisieren einer Organisation:
Admin Account anlegen
33 POST I_Registration (Admin-Account Credentials + 2. Faktor) 36 Status
TIM.UC_10060-02_01 5.1.2 AF - Bereitstellung eines Messenger-Service für eine Organisation:
Admin Login
2 POST /login (Client-Credentials) 4 status
TIM.UC_10060-02_02 5.1.2 AF - Bereitstellung eines Messenger-Service für eine Organisation:
Messenger Service erstellen
7 POST /create (Matrix-Domain) 25 status
TIM.UC_10063-01_01 5.1.6 AF - Austausch von Events zwischen Akteuren innerhalb einer Organisation:
Matrix-Request
2 Matrix-Request 6 HTTP(S) Forward
TIM.UC_10061-02_01 5.1.7 AF - Einladung von Akteuren außerhalb einer Organisation:
Einladung Sendersystem
1 POST /_matrix/client/r0/rooms/{roomsId}/invite 20 "Nutzer in den Raum eingeladen"
TIM.UC_10061-02_02 5.1.7 AF - Einladung von Akteuren außerhalb einer Organisation:
Einladung Empfangssystem
7 HTTP(S) Forward 17 HTTP(S) Forward
TIM.UC_10062-02_01 5.1.8 AF - Austausch von Events zwischen Akteuren außerhalb einer Organisation:
Event Sendersystem
2 Matrix-Request 6 Status
TIM.UC_10062-02_02 5.1.8 AF - Austausch von Events zwischen Akteuren außerhalb einer Organisation:
Event Empfangssystem(e)
9 HTTP(S) Forward 16 HTTP(S) Forward
TIM.UC_10036-01_01 TI-Messenger-Nutzer sucht Einträge im FHIR-Directory
(Client-Anfrage am TIM-FD)
3 POST /_matrix/client/r0/user/{userId}/openid/request_roken 4 HTTP Response
TIM.UC_10036-01_02 TI-Messenger-Nutzer sucht Einträge im FHIR-Directory
(Token Validierung von FHIR-VZD)
8 GET matrix.service-ti.de:{PORT}/_matrix/federation/v1/openid/userinfo?access_token=... 9 HTTP Response
TIM.UC_10234_01 Identifikation und Login eines Benutzers
(erhalte ID des sektoralen IDP)
2 GET
{homeserver_client_api_url}/login
3
200 OK
TIM.UC_10234_02 Identifikation und Login eines Benutzers
(SSO Request für sIDP)
6 GET
{homeserver_client_api_url}/login/sso/redirect/{sidp}
9
302 Redirect
{sektoraler_idp_url}/login/oauth/authorize
TIM.UC_10234_03 Identifikation und Login eines Benutzers
(auth_code an TIM-FD zur Prüfung)
18 GET
{redirect_uri}
23
200 OK
TIM.UC_10234_04 Identifikation und Login eines Benutzers
(Login)
24 POST
{homeserver_client_api_url}/login
25
200 OK

Hinweis:

Für die gelb-markierten Anwendungsfälle sollen entsprechend A_24464-* nur die Fehlerfälle in den Rohdaten übertragen werden (siehe A_24464).

5 Funktionsmerkmale

5.1 Einschränkung zu Anwendungsfall AF_10060 - Bereitstellung eines Messenger-Service für eine Organisation

Der nachfolgende Anwendungsfall beschreibt die Ergänzungen zur Einschränkung an "AF_10060 - Bereitstellung eines Messenger-Service für eine Organisation".

Tabelle 2: Einschränkung zu Anwendungsfall AF_10060

AF_10060 Bereitstellung eines Messenger-Service für eine Organisation
Beschreibung / Motivation
Um den Messenger-Service für Akteure in der Rolle "Versicherter" von anderen Produkttypen differenzieren zu können, soll dieser ausschließlich nur (im Auftrag) von gesetzlichen und privaten Krankenversicherungen angelegt werden dürfen. Die Domain des Messenger-Service ist in der Föderationsliste als Domain für Versicherte zu hinterlegen.
Vorbedingung Ein Akteur in der Rolle "Org-Admin" hat die Organisation mit einer SM(C)-B KTR bzw. über das KIM-Verfahren mit einer professionOID für Kostenträger: 1.2.276.0.76.4.59 registriert.
Ergebnis Ein Messenger-Service für Akteure in der Rolle "Versicherter" darf ausschließlich von Kostenträgern im Gesundheitswesen (=professionOID 1.2.276.0.76.4.59) instanziiert werden.
Die Domain des Messenger-Service ist in der Föderationsliste hinterlegt worden und das Feld "isInsurance" wurde mit "true" belegt.

A_25690 - AF_10060 - Messenger-Service für ePA - Bereitstellung nur für Kostenträger

Ein Messenger-Service für ePA MUSS nur von Kostenträgern im Gesundheitswesen (=professionOID 1.2.276.0.76.4.59) bereitgestellt werden können. [<=]

A_26000 - AF_10060 - Messenger-Service für ePA - Föderationslisteneintrag

Bei der Bereitstellung eines Messenger-Service für ePA MUSS beim Eintragen der Domain in der Föderationsliste der Wert von "isInsurance" mit "true" belegt werden. [<=]

5.2 Feature Identifikation und Login eines Benutzers

Versicherte erhalten von ihrer Krankenkasse eine App, die es ihnen ermöglicht, den TI-Messenger innerhalb des ePA FdV zu nutzen. Die Krankenkasse stellt den Versicherten Identifizierungsmöglichkeiten gemäß [gemSpec_IDP_Sek#Identifizierung und Authentifizierung des Nutzers] und einen IDP bereit, der es ermöglicht, die Versicherten der Krankenkasse zu authentifizieren und Identitätsinformationen der Versicherten in den Diensten der TI (wie hier am TI-Messenger Service) zu nutzen.

5.2.1 Anwendungsfall

AF_10234 - Identifikation und Login eines Benutzers

Damit Versicherte die Messenger-Funktion der ePA-App ihrer Krankenkasse nutzen können, müssen sich diese am IDP ihrer Krankenkasse identifizieren und erhalten damit Zugang zu deren TI-Messenger Service. Die Authentifizierung von Versicherten für die Registrierung von TI-Messenger Accounts und für das Login am Homeserver erfolgt am sektoralen IDP mittels OIDC.

Tabelle 3: AF - Identifikation und Login eines Benutzers

Attribute Bemerkung
Akteur Versicherter, welcher gleichzeitig auch das ePA-FdV benutzt.
Auslöser Der Akteur benutzt die Login- oder Registrierungs-Funktion seines TI-M Clients
Komponenten
  • TI-M Client im ePA-FdV
  • Messenger-Proxy
  • Matrix-Homeserver (als Relying Party des sektoralen IDP)
  • Sektoraler IDP
Eingangsdaten Login-Call am aufgerufenen Client des Akteurs
Ergebnis
  1. Der Akteur erhält einen nutzbaren Zugang zum TI-Messenger Service seiner Krankenkasse (bei Nutzung der Registrierungsfunktion).
  2. Akteur ist mit seinem Client am Matrix Homeserver eingeloggt und kann anschließend über diesen kommunizieren.
Ausgangsdaten
  • Neuer Nutzeraccount auf dem Homeserver (bei Nutzung der Registrierungsfunktion)
  • aktive User-Session im TI-M Client unter Benutzung eines gültigen access token
Diagrammvariablen
  • {homeserver_client_api_url}: Hostname des Matrix-Homeserver, z.B. https://myprovider.homeserver-tim.de, zzgl. Basispfad zum gültigen Client-API /_matrix/client/v3
  • {sidp}: ID des sektoralen IDPs, die vom Homeserver beauskunftet wird
  • {sektoraler_idp_url}: Der am Homeserver konfigurierte FQDN des sektoralen IDP als OIDC IDP
  • {redirect_uri}: Die vollständige Callback-Adresse für den OIDC Flow
  • {client_url}: URL der TI-M Clients

Die Laufzeitsicht zeigt sowohl die Registrierung eines Benutzer-Accounts als auch den Login eines Akteurs am Homeserver des TI-Messengers Service. Die in der Box "Verhaltensänderung, ..." dargestellte Änderung betrifft notwendige Anpassungen am Messenger-Proxy, um damit Redirects vom Homeserver aufzufangen, auszuwerten und anhand der Auswertung über einen entsprechende Endpoint am sektoralen IDP einen PAR (ein Pushed Authorization Request) nach dessen Vorgaben zu erstellen.


Abbildung 5 : Laufzeitsicht - Identifikation und Login eines Benutzers 

[<=]

A_25706 - AF_10234 - Erzeugung der MXID (Bei Registrierung)

Der TI-M FD ePA MUSS im Fall der Registrierung die MXID für die Accounts von Akteuren in der Rolle Versicherter nach folgender Bildungsregel erzeugen: @<KVNR>:<Matrix-Domain der Krankenkasse für Versicherte>. Die KVNR zur Verarbeitung entnimmt der Matrix-Homeserver aus dem id_token, das vom sektoralen IDP ausgestellt wurde (claim urn:telematik:claims:id). [<=]

A_25707 - AF_10234 - Erzeugung des Display Name

Der TI-M FD ePA SOLL im Fall der Registrierung oder des Logins den Display Name für die Accounts der Akteure in der Rolle Versicherter aus dem id_token vom sektoralen IDP übernehmen (claim urn:telematik:claims:display_name). Ist dies nicht möglich, so SOLL der TI-M FD ePA den Display Name sinnvoll aus anderen Bestandteilen des id_token zusammensetzen. [<=]

5.3 Berechtigungsmanagement - Anpassungen

5.3.1 Unterbindung der Versicherteneinladung

Der TI-M FD ePA soll verhindern, dass ein Versicherter einen anderen Versicherten einladen kann. Die folgende Grafik zeigt, welche Komponenten der Fachdienste, die zusätzliche Prüflogik übernehmen müssen. Die Versichertenprüfung soll an der Matrix-Client-Server-API durchgeführt werden sowie zur weiteren Absicherung ebenfalls an der Matrix-Server-Server-API zwischen den TI-M FD.

Abbildung 6: Prüfung auf Versichertenbeteiligung

Die Anpassungen an der Prüflogik des Messenger-Proxy werden in den folgenden Kapiteln näher erläutert.

Hinweis: Sofern ein Akteur, der nicht Versicherter ist, die Einladung(en) ausspricht, können auch mehrere Versicherte Teilnehmer eines Raumes sein und Nachrichten austauschen.

5.3.1.1 Client-Server Prüfungen

In der Funktion als Client-Server Proxy prüft der Messenger-Proxy, wie in der TI-M Basis beschrieben, eingehende Invite- Events der TI-M Clients (in der Abbildung 6 rot dargestellt) und fungiert so als Reverse-Proxy. Für den TI-M ePA muss der Messenger-Proxy zusätzlich zur in der TI-M Basis geforderten Föderationszugehörigkeit die Versicherteneinladung nach AF_10233 - AF_10233 Versicherteneinladung unterbinden verhindern.

5.3.1.2 Server-Server Prüfungen

In der Funktion als Server-Server Proxy prüft der Messenger-Proxy, wie in der TI-M Basis beschrieben, alle ausgehenden sowie eingehenden Events auf Föderationszugehörigkeit. Für den TI-M ePA muss die Prüfung zusätzlich die Versicherteneinladung nach AF_10233 - AF_10233 Versicherteneinladung unterbinden verhindern.

AF_10233 - AF_10233 Versicherteneinladung unterbinden

Dieser Anwendungsfall erweitert die in der TI-M Basis definierte Prüflogik für den Messenger-Proxy, neben der Föderationsprüfung ist zusätzlich zu prüfen, dass der Einladende und der Eingeladene nicht der Gruppe Versicherte zuzuordnen sind. Für die Prüfung der Zugehörigkeit verwendet der Messenger-Proxy die Information isInsurance aus der Föderationsliste.

Tabelle 4: AF - Versicherteneinladung unterbinden

Attribute Bemerkung
Auslöser Anfrage am Messenger Proxy
Komponenten Messenger-Proxy
Vorbedingung Szenario 1: Beide Kommunikationspartner haben einen Benutzeraccount mit einer Domain, welche in der Föderationsliste als "isInsurance" gekennzeichnet wurde (Kennzeichen für eine Versichertendomain).

Szenario 2: Mind. einer der Kommunikationspartner hat einen Benutzeraccount mit einer Domain, welche in der Föderationsliste NICHT als "isInsurance" gekennzeichnet wurde.
Eingangsdaten Matrix Invite Event
Ergebnis Szenario 1: Ablehnung der Einladung, wenn der Sender und der Empfänger beides Akteure in der Rolle Versicherter sind.

Szenario 2: Weiterleitung der Einladung, wenn der Sender oder der Empfänger kein Akteur in der Rolle Versicherter ist.

Abbildung 7: Versicherteneinladung unterbinden 

[<=]

A_25705 - AF_10233 - Versicherteneinladung unterbinden

Der Messenger-Proxy des TI-M FD ePA MUSS im Rahmen der Client-Server Prüfungen Anfragen auf Invite-Events prüfen. Sind der Sender und der Empfänger beide Akteure in der Rolle Versicherter dann MUSS die Einladung vom TI-Messenger-Proxy abgelehnt werden. Ein Akteur ist als Versicherter zu identifizieren, wenn die Domain seiner MXID über den Wert "true" im Feld "isInsurance" innerhalb der Föderationsliste verfügt. [<=]

A_25704 - AF_10233 - Versicherteneinladung erlauben

Der Messenger-Proxy des TI-M FD ePA MUSS im Rahmen der Server-Server Prüfungen Anfragen auf Invite-Events prüfen. Ist der Sender oder der Empfänger KEIN Akteur in der Rolle Versicherter, dann MUSS die Einladung vom TI-Messenger-Proxy weitergeleitet werden. Ein Akteur ist als Versicherter zu identifizieren, wenn die Domain seiner MXID über den Wert "true" im Feld "isInsurance" innerhalb der Föderationsliste verfügt. [<=]

5.3.1.3 Berechtigungsprüfung

Die folgende Grafik zeigt in der Zusammenfassung die für den TI-M ePA anzuwendenden Prüfregeln, am Beispiel der Verarbeitung eines Invite Events auf Seiten des Messenger-Service des eingeladenen Akteurs.

Abbildung 8: Berechtigungsprüfung TI-M_ePA

5.3.2 Weitere Anpassungen

A_25044-01 - Event Type für Berechtigungskonfiguration

Der TI-M Client ePA MUSS für die Ablage der Berechtigungskonfiguration in den Accountdaten des Matrix-Homeservers de.gematik.tim.account.permissionconfig.epa.v1 als Event Type verwenden. [<=]

A_25258-01 - Schema der Berechtigungskonfiguration

Die Daten der Berechtigungskonfiguration MÜSSEN dem JSON-Schema [api-messenger/src/schema/TI-M_ePA/permissionConfig_V1.json] entsprechen. [<=]

5.4 Push-Benachrichtigung im FdV

Eine besondere Herausforderung beim Frontend des Versicherten (FdV) besteht darin, dass eine App (das FdV) die Client-Logik zur Kommunikation mit drei unterschiedlichen Fachdiensten (ePA, E-Rezept, TI-M) sicherstellen muss. Um die Flexibilität hinsichtlich multipler Fachdienste und unterschiedlicher Clients sicherzustellen, muss das Push-Gateway für andere Fachdienste entsprechend separate Endpunkte zur Verfügung zu stellen, deren Ausgestaltung über die kommenden Spezifikationsreleases zum ePA-FdV oder dem E-Rezept im ePA-FdV erfolgen wird.

Die nachfolgende Grafik illustriert exemplarisch das zukünftige Szenario. Hier existiert bereits ein E-Rezept-Fachdienst, der über ein Push-Gateway die Push-Dienste von Google und Apple angebunden hat, um die E-Rezept-App sowohl unter Android als auch unter iOS mit Push-Benachrichtigungen zu versorgen. In diesem Szenario möchte eine Beispiel-Krankenkasse dem Versicherten eine App ("FdV App") zur Verfügung stellen, die Push-Benachrichtigungen der integrierten Fachdienste ePA, E-Rezept und TI-Messenger verarbeiten kann. Hierzu ist es notwendig, den bereits existierenden E-Rezept-Fachdienst anzubinden sowie auf Seiten des Versicherten (in der "FdV App") die Benachrichtigungen technisch von einander zu trennen.

Abbildung 9: Push-Gateway

Wie die Abbildung zeigt, stellt die Beispiel-Krankenkasse ein Push-Gateway für ihre FdV-App zur Verfügung und registriert die App beim Push-Anbieter. Durch die Registrierung erhält die App vom Anbieter ein Token, über welches die Anwendung beim Senden von Push-Benachrichtigungen eindeutig identifiziert werden kann. Dieses Token und die Information, welches Gateway zu verwenden ist, stellt die App den von ihr genutzten Fachdiensten zur Verfügung. Dazu ist es notwendig, dass die in der Grafik gelb markierten Schnittstellen öffentlich verfügbar und für beliebige Clients nutzbar sein müssen. Die Schnittstellen erlauben einem Client dem Fachdienst das zu nutzende Push-Gateway und den zu verwendenden Provider zu definieren.

Zusätzlich muss der Client über die Schnittstelle den Token bereitstellen können, über den die App vom Push-Provider eindeutig zu identifizieren ist (Bsp.: [Client-Server API/#post_matrixclientv3pushersset]). Ebenfalls müssen die Schnittstellen der Fachdienste zu den Gateways öffentlich einsehbar sein, damit die gematiker Krankenkasse an ihrem Push-Gateway eine Schnittstelle bereitstellen kann, die vom E-Rezept-Fachdienst auch verstanden wird (Bsp.: [Push Gateway API/#post_matrixpushv1notify]). Die beiden deckungsgleichen Schnittstellen sind rot markiert. Die grün markierten Schnittstellen am Push Gateway der gematiker Krankenkasse werden im Beispielszenario nicht von anderen Apps genutzt, müssen jedoch auch öffentlich verfügbar sein, damit andere App-Entwickler für ihre Anwendungen ein Push-Gateway mit identischen Schnittstellen bereitstellen können.

Das vorgestellte Szenario hat den Vorteil, dass die Push-Anbieter spezifischen Credentials beim Push-Gateway des App-Anbieters verbleiben können und dass es dem App-Anbieter überlassen ist zu entscheiden, wie er die Trennung der Inhalte übernimmt. Z.B. kann die gematiker Krankenkasse selbst in der Logik ihres Gateways entscheiden, ob sie in den Inhalt der Benachrichtigung einen Indikator aufnimmt, welcher Fachdienst die Benachrichtigung gesendet hat oder z.B. bei Nutzung von FCM diese Unterscheidung über eigene Topics für die verschiedenen Fachdienste realisiert.

6 Anhang A – Verzeichnisse

6.1 Abkürzungen

Tabelle 5: Im Dokument verwendete Abkürzungen

Kürzel
Erläuterung
ePA elektronische Patientenakte
FD Fachdienst
FdV Frontend des Versicherten
IdP Identity Provider
KTR Kostenträger
PKI Public Key Infrastructure
VZD Verzeichnisdienst

6.2 Glossar

Tabelle 6: Im Dokument verwendete Begriffe

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.

6.3 Abbildungsverzeichnis

6.4 Tabellenverzeichnis

6.5 Referenzierte Dokumente

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

Tabelle 7: Referenzierte Dokumente der gematik

[Quelle]
Herausgeber: Titel
[gemAnbT_IDP-Sek_KTR_ATV] Anbietertypsteckbrief Prüfvorschrift Anbieter
Sektoraler Identity Provider für den Sektor Kostenträger
[gemGlossar] gematik: Einführung der Gesundheitskarte - Glossar
[gemKPT_Betr] gematik: Betriebskonzept Online-Produktivbetrieb
[gemSpec_IDP_FD] gematik: Spezifikation Identity Provider - Nutzungsspezifikation für Fachdienste
[gemSpec_IDP_Frontend] gematik: Spezifikation Identity Provider - Frontend
[gemSpec_IDP_Sek] gematik: Spezifikation Sektoraler Identity Provider
[gemSpec_TI-M_Basis] gematik: Spezifikation TI-Messenger (Basis)

6.5.2 Weitere Dokumente

Tabelle 8: Weitere Dokumente

[Quelle]
Herausgeber (Erscheinungsdatum): Titel
[Client-Server API] Matrix Foundation: Matrix Specification - Client-Server API
https://spec.matrix.org/v1.11/client-server-api/
[Push Gateway API] Matrix Foundation: Matrix Specification - Push Gateway API
https://spec.matrix.org/v1.11/push-gateway-api/
[RFC2119] IETF: Key words for use in RFCs to Indicate Requirement Levels
https://datatracker.ietf.org/doc/html/rfc2119