You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.adoc
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -51,7 +51,7 @@ Die folgende Abbildung gibt einen Überblick über die Systemarchitektur des *TI
51
51
52
52
image::System_overview.png[width="100%"]
53
53
54
-
TIP: Auf die Schnittstellen zur Autentisierung am *Auth-Service* des *VZD-FHIR-Directory* wird in der oben gezeigten Abbildung verzichtet. Die Informationen hierzu können in dem entsprechenden Kapitel für das *VZD-FHIR-Directory* link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#2-fhirdirectoryauthenticationapis[hier] nachgelesen werden.
54
+
TIP: Auf die Schnittstellen zur Autentisierung am *Auth-Service* des *VZD-FHIR-Directory* wird in der oben gezeigten Abbildung verzichtet. Die Informationen hierzu können in dem entsprechenden Kapitel für das *VZD-FHIR-Directory* link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#fhirdirectoryauthenticationapis[hier] nachgelesen werden.
Copy file name to clipboardExpand all lines: docs/Client/Client.adoc
+11-11Lines changed: 11 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@ Im Kontext des *TI-Messenger-Dienstes* wird zwischen den folgenden Ausprägungen
24
24
* *TI-Messenger-Clients für Akteure* und
25
25
* *TI-Messenger-Clients mit Administrationfunktionen*.
26
26
27
-
Beide Arten von Clients basieren auf dem offenen Kommunikationsprotokoll Matrix und werden auf dem Endgerät eines Akteurs verwendet. In der folgenden Dokumentation werden die zwei Ausprägungen der Clients beschrieben.
27
+
Beide Arten von Clients basieren auf dem offenen Kommunikationsprotokoll Matrix und werden auf dem Endgerät eines Akteurs verwendet. In der folgenden Dokumentation werden die zwei Ausprägungen der Clients beschrieben.
28
28
29
29
IMPORTANT: Die Seite ergänzt die Spezifikation gemäß link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Client_V1.1.1.pdf[[gemSpec_TI-Messenger-Client]], die als Grundlage für das Verständnis vorrausgesetzt wird.
NOTE: Der Aufruf der vom *Matrix-Homeserver* angebotenen Schnittstellen der [Matrix - Client-Server API] erfolgt immer über den *Messenger-Proxy*.
41
41
42
-
In den folgenden Kapiteln werden die vom _TI-Messenger Modul_ zu verwendenen Schnittstellen sowie die vom *TI-Messenger-Client* bereitzustellenden Funktionen beschrieben.
42
+
In den folgenden Kapiteln werden die vom _TI-Messenger Modul_ zu verwendenen Schnittstellen sowie die vom *TI-Messenger-Client* bereitzustellenden Funktionen beschrieben.
43
43
44
44
===== Matrix - Client-Server API
45
45
Der *Matrix-Homeserver* muss die REST-Schnittstellen gemäß der Matrix https://spec.matrix.org/v1.3/client-server-api/[[Client-Server API]] für den *TI-Messenger-Client* zur Verfügung stellen. Diese müssen für die *TI-Messenger-Clients* aus dem Internet angeboten werden. Für die Verarbeitung der `Matrix-Events` muss der *TI-Messenger-Client* die in der [Matrix-Client-Server API] clientspezifischen Verhaltensweisen implementieren. Diese sind in der API mit dem Keyword _behaviour_ gekennzeichnet. Unter folgendem https://spec.matrix.org/v1.3/client-server-api/#client-behaviour-21[Link] ist ein Beispiel dargestellt.
@@ -95,13 +95,13 @@ NOTE: In der veröffentlichten und zulassungsrelevanten Spezifikationsversion v1
95
95
- `/search` +
96
96
- `/owner`
97
97
98
-
Für den Aufruf der beiden Endpunkte `/search` und `/owner` am *FHIR-Proxy* für die Suche und Pflege von Einträgen werden Zugriffstoken benötigt, um die Berechtigung für den Zugriff nachzuweisen. Daher muss der *TI-Messenger-Client* zuvor am *Auth-Service* des *VZD-FHIR-Directory* die notwendigen Token anfragen. Im folgenden werden die Aufrufe der Endpunkte weiter beschrieben.
98
+
Für den Aufruf der beiden Endpunkte `/search` und `/owner` am *FHIR-Proxy* für die Suche und Pflege von Einträgen werden Zugriffstoken benötigt, um die Berechtigung für den Zugriff nachzuweisen. Daher muss der *TI-Messenger-Client* zuvor am *Auth-Service* des *VZD-FHIR-Directory* die notwendigen Token anfragen. Im folgenden werden die Aufrufe der Endpunkte weiter beschrieben.
99
99
100
100
===== Auth-Service
101
101
Der *Auth-Service* des *VZD-FHIR-Directory* bietet die zwei Endpunkte an, die die beiden Zugriffstoken (`search-accesstoken` und `owner-accesstoken`) ausstellen. Die zwei Endpunkte werden in den folgenden Kapiteln weiter beschrieben.
102
102
103
103
====== /tim-authenticate
104
-
Für den Zugriff auf die Suchfunktionalität von FHIR-Ressourcen (`/search`-Endpunkt) authentisiert sich der *TI-Messenger-Client* gegenüber dem *VZD-FHIR-Directory* mit einem 3rd-Party-Token (`Matrix-OpenID Token`), das er von seinem *Matrix-Homeserver* anfordern kann (siehe link:https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3useruseridopenidrequest_token[Matrix OpenID Token]). Dieses 3rd-Party-Token benötigt der *TI-Messenger-Client*, um es beim `/tim-authenticate`-Endpunkt des *VZD-FHIR-Directory* gegen ein `search-accesstoken` einzutauschen. Bei Aufruf des Endpunktes `/tim-authenticate` ist es erforderlich, das 3rd-Party-Token (`Matrix-OpenID-Token`) im Header sowie die URL des *Matrix-Homeservers* im Parameter `MXID` zu übergeben. Der Aufruf des `/tim-authenticate`-Endpunktes ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Authenticate.adoc#21-authenticate-for-the-search-endpoint[hier] beschrieben.
104
+
Für den Zugriff auf die Suchfunktionalität von FHIR-Ressourcen (`/search`-Endpunkt) authentisiert sich der *TI-Messenger-Client* gegenüber dem *VZD-FHIR-Directory* mit einem 3rd-Party-Token (`Matrix-OpenID Token`), das er von seinem *Matrix-Homeserver* anfordern kann (siehe link:https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3useruseridopenidrequest_token[Matrix OpenID Token]). Dieses 3rd-Party-Token benötigt der *TI-Messenger-Client*, um es beim `/tim-authenticate`-Endpunkt des *VZD-FHIR-Directory* gegen ein `search-accesstoken` einzutauschen. Bei Aufruf des Endpunktes `/tim-authenticate` ist es erforderlich, das 3rd-Party-Token (`Matrix-OpenID-Token`) im Header sowie die URL des *Matrix-Homeservers* im Parameter `MXID` zu übergeben. Der Aufruf des `/tim-authenticate`-Endpunktes ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-for-the-search-endpoint[hier] beschrieben.
105
105
106
106
====== /owner-authenticate
107
107
Für die Pflege von FHIR-Ressourcen (`/owner`-Endpunkt) authentisiert sich der *TI-Messenger-Client* gegenüber dem *VZD-FHIR-Directory* unter Verwendung einer Smartcard (HBA), um ein `owner-accesstoken` vom *Auth-Service* zu erhalten. Für die Authentisierung mittels Smartcard ist der von der gematik bereitgestellte link:/docs/IDP/idp.adoc[zentrale IDP-Dienst] zu verwenden.
@@ -114,10 +114,10 @@ Der durchzuführende Authorization Code Flow ist link:/docs/IDP/idp.adoc#4-autho
114
114
Der *FHIR-Proxy* bietet zwei Endpunkte zur Suche und Pflege von FHIR-Ressourcen an, die nur unter Verwendung eines gültigen Zugriffstoken aufgerufen werden können. Die zwei Endpunkte werden in den folgenden Kapiteln weiter beschrieben.
115
115
116
116
====== /search
117
-
Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectorySearchAPI` den Endpunkt `/search` an, um FHIR-Ressourcen zu suchen. Um diesen Endpunkt aufrufen zu können, wird ein `search-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle für die Suche von FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Search.adoc[search API examples] beschrieben.
117
+
Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectorySearchAPI` den Endpunkt `/search` an, um FHIR-Ressourcen zu suchen. Um diesen Endpunkt aufrufen zu können, wird ein `search-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle für die Suche von FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Search.adoc[search API examples] beschrieben.
118
118
119
119
====== /owner
120
-
Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectoryOwnerAPI` den Endpunkt `/owner` an, um FHIR-Ressourcen zu suchen und eigene Einträge zu pflegen. Um diesen Endpunkt aufrufen zu können, wird ein `owner-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben.
120
+
Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectoryOwnerAPI` den Endpunkt `/owner` an, um FHIR-Ressourcen zu suchen und eigene Einträge zu pflegen. Um diesen Endpunkt aufrufen zu können, wird ein `owner-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben.
121
121
122
122
==== Auth Modul
123
123
Über das _Auth Modul_ wird die Kommunikation mit Smartcards (HBA) realisiert, um diese zur Authentisierung am `/owner-authenticate`-Endpunkt zu ermöglichen. Im Folgenden wird der Prozess kurz skizziert, nachdem beim Aufruf des `/owner-authenticate`-Endpunktes das _Auth Modul_ einen `Redirect` zum `Authorization Endpoint` des *IDP-Dienstes* vom *Auth-Service* erhalten hat.
@@ -130,7 +130,7 @@ An dem Endpunkt `/signin-gematik-idp-dienst` übergibt das _Auth Modul_ des *TI-
130
130
131
131
=== Bereitstellung weiterer Funktionalitäten
132
132
==== Sichbarkeit
133
-
*TI-Messenger-Clients* müssen über eine Funktion verfügen die die Sichtbarkeit eines Akteurs für den *TI-Messenger-Dienst* im Personenverzeichnis über den `/owner`-Endpunkt des *VZD-FHIR-Directory* ein bzw. ausschalten kann. Wenn ein Akteur den Status seines Endpunktes von `active` nach `off` link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc#232-update-endpoint-put[ändert], muss der *TI-Messenger-Client* prüfen, ob diese `MXID` auch im Organisationsverzeichnis eingetragen ist. Wird die `MXID` ebenfalls im Organisationsverzeichnis gefunden und ist der hinterlegte Status in diesem Verzeichnis active, dann ist im *TI-Messenger-Client* dem Akteur ein entsprechender Hinweis anzuzeigen, dass eine Inkonsistenz in der hinterlegten Sichtbarkeit vorliegt.
133
+
*TI-Messenger-Clients* müssen über eine Funktion verfügen die die Sichtbarkeit eines Akteurs für den *TI-Messenger-Dienst* im Personenverzeichnis über den `/owner`-Endpunkt des *VZD-FHIR-Directory* ein bzw. ausschalten kann. Wenn ein Akteur den Status seines Endpunktes von `active` nach `off` link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc#update-endpoint-put[ändert], muss der *TI-Messenger-Client* prüfen, ob diese `MXID` auch im Organisationsverzeichnis eingetragen ist. Wird die `MXID` ebenfalls im Organisationsverzeichnis gefunden und ist der hinterlegte Status in diesem Verzeichnis active, dann ist im *TI-Messenger-Client* dem Akteur ein entsprechender Hinweis anzuzeigen, dass eine Inkonsistenz in der hinterlegten Sichtbarkeit vorliegt.
134
134
135
135
IMPORTANT: Aus dem Hinweis muss hervorgehen, dass ein Kontaktieren des Administrators seiner Organisation notwendig ist, um die gewünschte Sichtbarkeit ebenfalls im Organisationsverzeichnis zu hinterlegen.
136
136
@@ -176,14 +176,14 @@ Der Administrator einer Organisation (in der Rolle "Org-Admin") verwaltet mittel
176
176
177
177
*Authentisierung*
178
178
179
-
Für den Zugriff auf die `/owner`-Schnittstelle am *FHIR-Proxy* wird ein `owner-accesstoken` benötigt, das vom `/owner-authenticate`-Endpunkt des *Auth-Service* ausgestellt wird. Zur Authentisierung am Endpunkt fragt der *Org-Admin-Client* beim zuständigen *Registrierungs-Dienst* einen `RegService-OpenID-Token` an, welcher am `/owner-authenticate`-Endpunkt gegen ein `owner-accesstoken` ausgetauscht wird. Ein Beispiel für die Authentisierung ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Authenticate.adoc#231-authenticate-with-an-regservice-openid-token[hier] zu finden.
179
+
Für den Zugriff auf die `/owner`-Schnittstelle am *FHIR-Proxy* wird ein `owner-accesstoken` benötigt, das vom `/owner-authenticate`-Endpunkt des *Auth-Service* ausgestellt wird. Zur Authentisierung am Endpunkt fragt der *Org-Admin-Client* beim zuständigen *Registrierungs-Dienst* einen `RegService-OpenID-Token` an, welcher am `/owner-authenticate`-Endpunkt gegen ein `owner-accesstoken` ausgetauscht wird. Ein Beispiel für die Authentisierung ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-with-an-regservice-openid-token[hier] zu finden.
180
180
181
181
*Bearbeitung*
182
182
183
-
Zur Pflege der FHIR-Ressourcen ist es erforderlich, dass der *Org-Admin-Client* den Endpunkt `/owner` unter Verwendung des `owner-accesstoken` (welches im Authorization Header mit übergeben werden muss) aufruft. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in der link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben. Der vom *Org-Admin-Client* angebotene Funktionsumfang ist:
183
+
Zur Pflege der FHIR-Ressourcen ist es erforderlich, dass der *Org-Admin-Client* den Endpunkt `/owner` unter Verwendung des `owner-accesstoken` (welches im Authorization Header mit übergeben werden muss) aufruft. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in der link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben. Der vom *Org-Admin-Client* angebotene Funktionsumfang ist:
184
184
185
-
* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc#22-administration-of-resource-healthcareservice[HealthcareServices] und
186
-
* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc#23-administration-of-resource-endpoint--metatagoriginowner[Endpoints].
185
+
* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc#administration-of-resource-healthcareservice[HealthcareServices] und
186
+
* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc#administration-of-resource-endpoint-meta-tag-originowner[Endpoints].
187
187
188
188
==== Funktionsaccounts
189
189
Einrichtungen im Gesundheitswesen sind sehr unterschiedlich strukturiert und wollen hinsichtlich ihrer Erreichbarkeit flexibel eigene Strukturen abbilden können. Daher sind beim *TI-Messenger-Dienst* Funktionsaccounts notwendig, die es ermöglichen, Akteure unterhalb der Struktur erreichbar zu machen. Hierfür ist es erforderlich das über den *Org-Admin-Client* ein `Endpoint` im *FHIR-Directory* angelegt wird.
Copy file name to clipboardExpand all lines: docs/FHIR-Directory/FHIR-Directory.adoc
+5-5Lines changed: 5 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -63,19 +63,19 @@ Weitere Informationen zu den Verzeichnistypen können link:https://github.com/ge
63
63
64
64
== OAuth-Service
65
65
Der *OAuth-Service* stellt ein `ti-provider-accesstoken` aus, welches am `/ti-provider-authenticate`-Endpunkt übergeben werden muss. Hierfür muss sich ein Anbieter eines *TI-Messenger-Fachdienstes* mittels seiner link:/docs/Fachdienst/Fachdienst.adoc#214-beantragung-der-ti-provider-credentials-am-vzd-fhir-directory[Zugangsdaten] am OAuth-Service authentisieren.
66
-
Der Aufruf des Endpunktes kann https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#22-authenticate-for-the-provider-api[hier] nachgelesen werden.
66
+
Der Aufruf des Endpunktes kann https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-for-the-provider-api[hier] nachgelesen werden.
67
67
68
68
== Auth-Service
69
-
Der *Auth-Service* stellt Zugriffstoken aus, die für den Zugriff auf die Endpunkte am *FHIR-Proxy* benötigt werden. Der Aufruf der Endpunkte am *Auth-Service* ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#2-fhirdirectoryauthenticationapis[dort] beschrieben.
69
+
Der *Auth-Service* stellt Zugriffstoken aus, die für den Zugriff auf die Endpunkte am *FHIR-Proxy* benötigt werden. Der Aufruf der Endpunkte am *Auth-Service* ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#fhirdirectoryauthenticationapis[dort] beschrieben.
70
70
71
71
== FHIR-Proxy
72
72
Der *FHIR-Proxy* gibt Zugriff auf das *FHIR-Directory* unter Vorlage eines validen `ACCESS_TOKEN` und somit auf die FHIR-Ressourcen. Die vom *FHIR-Proxy* zur Verfügung gestellten Endpunkte werden für die Suche und Pflege von FHIR-Ressourcen verwendet sowie zur Pflege eigener TIM Provider Einträge. Der Aufruf der Endpunkte am *FHIR-Proxy* sind der folgenden Aufzählung zu entnehmen:
TIP: Die Anbieter eines *TI-Messenger-Fachdienstes* nutzen die Schnittstelle `/tim-provider-services`, um die Föderationsliste abzufragen und um die Domains der von ihnen betriebenen *Messenger-Services* als Teil der TI-Messenger Föderation zu verwalten.
0 commit comments